@apexops/cli 0.10.0-next.5 → 0.11.0-next.1

package/assets/schemas/governance-baseline.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/jonathan-vella/apex-vnext/schemas/governance-baseline.schema.json",
+  "title": "APEX Governance Baseline",
+  "description": "Shape of .github/data/governance-policy-baseline.json produced by the governance-policy-baseline workflow. Wraps per-subscription governance-constraints-v1 envelopes.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "coverage_status",
+    "subscriptions_discovered",
+    "subscriptions_processed",
+    "subscriptions_skipped",
+    "subscriptions_excluded",
+    "summary",
+    "subscriptions"
+  ],
+  "additionalProperties": false,
+  "oneOf": [
+    {
+      "required": ["management_group_id"],
+      "not": { "required": ["subscription_id"] }
+    },
+    {
+      "required": ["subscription_id"],
+      "not": { "required": ["management_group_id"] }
+    }
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "governance-baseline-v2"
+    },
+    "management_group_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "subscription_id": {
+      "description": "Standalone collection root; mutually exclusive with management_group_id.",
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+    },
+    "coverage_status": {
+      "type": "string",
+      "enum": ["COMPLETE", "PARTIAL"]
+    },
+    "subscriptions_discovered": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "subscriptions_processed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "subscriptions_skipped": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "subscriptions_excluded": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["subscription_id", "reason"],
+        "additionalProperties": true,
+        "properties": {
+          "subscription_id": { "type": "string" },
+          "reason": {
+            "type": "string",
+            "enum": ["disabled", "AAD_quota", "unreadable", "processing_error"]
+          },
+          "detail": { "type": "string" },
+          "quota_id": { "type": "string" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["total_findings", "total_blockers", "total_auto_remediate", "subscriptions_complete"],
+      "additionalProperties": true,
+      "properties": {
+        "total_findings": { "type": "integer", "minimum": 0 },
+        "total_blockers": { "type": "integer", "minimum": 0 },
+        "total_auto_remediate": { "type": "integer", "minimum": 0 },
+        "subscriptions_complete": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "subscriptions": {
+      "type": "object",
+      "description": "Map of subscription ID to governance-constraints-v1 envelope. Each value must be a valid governance-constraints-v1 envelope.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["schema_version", "subscription_id", "discovered_at", "findings"],
+        "additionalProperties": true,
+        "properties": {
+          "schema_version": { "type": "string", "const": "governance-constraints-v1" },
+          "subscription_id": { "type": "string" },
+          "discovered_at": { "type": "string" },
+          "source": { "type": "string" },
+          "discovery_status": { "type": "string" },
+          "discovery_metadata": {
+            "type": "object",
+            "properties": {
+              "scope": {
+                "type": "object",
+                "properties": {
+                  "coverage": { "const": "subscription-and-descendants-v1" }
+                }
+              }
+            }
+          },
+          "findings": { "type": "array" },
+          "policies": false,
+          "tags_required": { "type": "array" },
+          "allowed_locations": { "type": "array" }
+        }
+      }
+    }
+  }
+}

package/dist/assets.d.ts

@@ -4,13 +4,16 @@ export interface BundledAssetMapping {
     sourceRoot?: string;
     generatedRoot?: string;
     generatedPath?: string;
+    entries?: Array<{
+        source: string;
+        target: string;
+    }>;
 }
 export interface BundledAssetSource {
     kind: "repository-file" | "generated";
     path?: string;
     mapping?: string;
     composition?: string;
-    roleId?: string;
     sourcePath?: string;
     sourceHash?: string;
     clientId?: string;
@@ -24,7 +27,7 @@ export interface BundledAssetFile {
     bytes: number;
 }
 export interface BundledClientProjection {
-    id: "github-copilot-cli" | "github-copilot-vscode";
+    id: "github-copilot-cli";
     files: string[];
     digest: string;
 }
@@ -48,9 +51,18 @@ export interface BundledAssetManifest {
         digest: string;
     };
 }
+/** The apex Agent Plugin; files it owns are never copied into or checked in a consumer workspace. */
+export interface BundledPluginDeclaration {
+    name: "apex";
+    marketplace: "apex-plugins";
+    marketplaceRepository: "jonathan-vella/apex-plugins";
+    ownedFiles: string[];
+    ownedDirectories: string[];
+}
 export interface BundledAssets {
     root: string;
     customizations: string;
+    plugin: BundledPluginDeclaration;
     clientProjections: Readonly<Record<BundledClientProjection["id"], string>>;
     config: string;
     capabilityPacks: string;
@@ -65,5 +77,9 @@ export declare function verifyBundleDeclarations(manifest: BundledAssetManifest,
 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>;
+/** True when the apex plugin, not the workspace projection, owns this workspace-relative path. */
+export declare function pluginOwnsPath(plugin: BundledPluginDeclaration, path: string): boolean;
+/** Reads only the plugin declaration from the bundled manifest; full asset verification stays in resolveBundledAssets. */
+export declare function readBundledPluginDeclaration(): Promise<BundledPluginDeclaration>;
 export declare function resolveBundledAssets(): Promise<BundledAssets>;
 //# sourceMappingURL=assets.d.ts.map

package/dist/assets.js

@@ -7,7 +7,6 @@ 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) {
@@ -19,6 +18,13 @@ function projectionTarget(clientId) {
 function portablePath(path) {
     return path.split(sep).join("/");
 }
+function comparablePath(path) {
+    const resolved = resolve(path);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function samePath(left, right) {
+    return comparablePath(left) === comparablePath(right);
+}
 function safeRelativePath(path) {
     return (path.length > 0 &&
         !path.includes("\\") &&
@@ -34,10 +40,12 @@ function assertContained(root, path) {
     }
 }
 export async function readBundledFile(root, relativePath, beforeOpen = async () => { }, expectedIdentity) {
-    const path = resolve(root, relativePath);
-    assertContained(root, path);
+    const absoluteRoot = resolve(root);
+    const path = resolve(absoluteRoot, relativePath);
+    assertContained(absoluteRoot, path);
+    const canonicalRoot = await realpath(absoluteRoot);
     const resolved = await realpath(path);
-    assertContained(root, resolved);
+    assertContained(canonicalRoot, resolved);
     const initialMetadata = await lstat(path, { bigint: true });
     const identity = expectedIdentity ?? { dev: initialMetadata.dev, ino: initialMetadata.ino };
     if (initialMetadata.isSymbolicLink() || !initialMetadata.isFile()) {
@@ -59,8 +67,8 @@ export async function readBundledFile(root, relativePath, beforeOpen = async ()
         }
         const descriptorPath = process.platform === "linux" ? `/proc/self/fd/${handle.fd}` : path;
         const openedPath = await realpath(descriptorPath);
-        assertContained(root, openedPath);
-        if (openedPath !== resolved) {
+        assertContained(canonicalRoot, openedPath);
+        if (!samePath(openedPath, resolved)) {
             throw new Error(`Bundled asset path changed during verification: ${relativePath}`);
         }
         return await handle.readFile();
@@ -164,6 +172,7 @@ export async function verifyBundledAssetManifest(root, manifest) {
     if (mappings.size !== manifest.composition.mappings.length)
         throw new Error("Duplicate bundled asset mapping ID");
     const generatedDestinations = [];
+    const explicitTargets = new Map();
     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}`);
@@ -173,19 +182,50 @@ export async function verifyBundledAssetManifest(root, manifest) {
                 mapping.sourceRoot !== undefined ||
                 mapping.generatedRoot !== undefined)
                 throw new Error(`Invalid bundled asset mapping: ${mapping.id}`);
-            generatedDestinations.push(mapping.generatedPath);
+            generatedDestinations.push({ path: mapping.generatedPath, mapping });
         }
         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}/`);
+        else if (mapping.entries === undefined) {
+            generatedDestinations.push({ path: `${mapping.generatedRoot}/`, mapping });
+        }
+        if (mapping.entries !== undefined) {
+            if (mapping.mode !== "copy-entries" ||
+                !Array.isArray(mapping.entries) ||
+                mapping.entries.length === 0 ||
+                mapping.entries.some((entry) => entry === null ||
+                    typeof entry !== "object" ||
+                    typeof entry.source !== "string" ||
+                    typeof entry.target !== "string" ||
+                    !safeRelativePath(entry.source) ||
+                    !safeRelativePath(entry.target) ||
+                    !entry.source.startsWith(`${mapping.sourceRoot}/`) ||
+                    !entry.target.startsWith(`${mapping.generatedRoot}/`)) ||
+                new Set(mapping.entries.map(({ source }) => source)).size !== mapping.entries.length)
+                throw new Error(`Invalid bundled asset copy entries: ${mapping.id}`);
+            for (const entry of mapping.entries) {
+                if (explicitTargets.has(entry.target))
+                    throw new Error(`Overlapping bundled asset mapping destination: ${entry.target}`);
+                explicitTargets.set(entry.target, mapping.id);
+                generatedDestinations.push({ path: entry.target, mapping });
+            }
+        }
     }
     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}`);
+        if (generatedDestinations.some((candidate, candidateIndex) => candidateIndex !== index &&
+            (destination.path.startsWith(candidate.path) || candidate.path.startsWith(destination.path)) &&
+            !(destination.mapping.entries !== undefined &&
+                candidate.mapping.mode === "copy-tree" &&
+                destination.path.startsWith(candidate.path) &&
+                destination.mapping.entries.every(({ source }) => !source.startsWith(`${candidate.mapping.sourceRoot}/`))) &&
+            !(candidate.mapping.entries !== undefined &&
+                destination.mapping.mode === "copy-tree" &&
+                candidate.path.startsWith(destination.path) &&
+                candidate.mapping.entries.every(({ source }) => !source.startsWith(`${destination.mapping.sourceRoot}/`)))))
+            throw new Error(`Overlapping bundled asset mapping destination: ${destination.path}`);
     }
     const paths = new Set();
     for (const file of manifest.files) {
@@ -201,15 +241,20 @@ export async function verifyBundledAssetManifest(root, manifest) {
             const mapping = mappings.get(file.source.mapping ?? "");
             if (!safeRelativePath(file.source.path ?? "") ||
                 mapping === undefined ||
-                mapping.mode === "compose-json" ||
+                !["copy-tree", "copy-entries"].includes(mapping.mode) ||
+                (explicitTargets.has(file.path) && explicitTargets.get(file.path) !== mapping.id) ||
                 !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("/")) {
+                (mapping.entries !== undefined
+                    ? !mapping.entries.some(({ source, target }) => source === file.source.path && target === file.path)
+                    : 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") {
+            if (explicitTargets.has(file.path))
+                throw new Error(`Invalid bundled asset source: ${file.path}`);
             const mapping = mappings.get(file.source.composition ?? "");
             if (mapping === undefined ||
                 (mapping.mode === "compose-json"
@@ -219,8 +264,9 @@ export async function verifyBundledAssetManifest(root, manifest) {
             }
             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" ||
+                if (file.source.clientId !== "github-copilot-cli" ||
+                    file.source.adapterVersion !== "1.12.0" ||
+                    "roleId" in file.source ||
                     !safeRelativePath(file.source.target ?? "") ||
                     !file.path.startsWith(expectedPrefix) ||
                     file.path !== `${expectedPrefix}${file.source.target}` ||
@@ -233,9 +279,13 @@ export async function verifyBundledAssetManifest(root, manifest) {
         else
             throw new Error(`Invalid bundled asset source: ${file.path}`);
     }
+    for (const target of explicitTargets.keys()) {
+        if (!paths.has(target))
+            throw new Error(`Missing bundled asset copy entry: ${target}`);
+    }
     const projectionIds = new Set();
     for (const projection of manifest.projections) {
-        if (!["github-copilot-cli", "github-copilot-vscode"].includes(projection.id) ||
+        if (projection.id !== "github-copilot-cli" ||
             projectionIds.has(projection.id) ||
             !Array.isArray(projection.files) ||
             projection.files.length !== new Set(projection.files).size ||
@@ -246,7 +296,7 @@ export async function verifyBundledAssetManifest(root, manifest) {
         }
         projectionIds.add(projection.id);
     }
-    if (projectionIds.size !== 2)
+    if (projectionIds.size !== 1)
         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))) {
@@ -264,7 +314,7 @@ export async function verifyBundledAssetManifest(root, manifest) {
     verifyBundleDeclarations(manifest, customizationManifest, runtimeBundle);
     const sharedFiles = customizationManifest.sharedFiles;
     const sharedDirectories = (customizationManifest.sharedDirectories ?? []);
-    const roles = customizationManifest.roles;
+    const plugin = pluginDeclaration(customizationManifest.plugin);
     const declarations = customizationManifest.clientProjections;
     if (!Array.isArray(sharedFiles) ||
         sharedFiles.length !== new Set(sharedFiles).size ||
@@ -272,20 +322,17 @@ export async function verifyBundledAssetManifest(root, manifest) {
         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);
+        projectionTarget(file.source.clientId);
         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) {
+        if (canonical?.source.kind !== "repository-file" ||
+            canonical.sha256 !== file.source.sourceHash ||
+            canonical.sha256 !== file.sha256) {
             throw new Error(`Generated client projection source binding mismatch: ${file.path}`);
         }
     }
@@ -294,18 +341,17 @@ export async function verifyBundledAssetManifest(root, manifest) {
         sharedDirectories.some((directory) => path.startsWith(`customizations/${directory}/`)))
         .map(({ path }) => path.slice("customizations/".length));
     for (const declaration of declarations) {
-        const target = projectionTarget(declaration.id);
+        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();
+        const expectedTargets = [...new Set([...sharedFiles, ...sharedDirectoryFiles, ...declaration.files])];
+        const reintroduced = expectedTargets.find((path) => pluginOwnsPath(plugin, path));
+        if (reintroduced !== undefined) {
+            throw new Error(`Bundled client projection carries a plugin-owned file: ${reintroduced}`);
+        }
+        const expected = expectedTargets.map((path) => `${declaration.generatedRoot}/${path}`).sort();
         if (!safeRelativePath(declaration.generatedRoot) ||
             projection === undefined ||
             JSON.stringify(projection.files) !== JSON.stringify(expected)) {
@@ -316,16 +362,50 @@ export async function verifyBundledAssetManifest(root, manifest) {
         throw new Error("Bundled asset lock mismatch");
     }
 }
+function pluginDeclaration(value) {
+    const plugin = value;
+    const paths = (entries) => Array.isArray(entries) &&
+        entries.length === new Set(entries).size &&
+        entries.every((entry) => typeof entry === "string" && safeRelativePath(entry));
+    if (plugin === null ||
+        typeof plugin !== "object" ||
+        plugin.name !== "apex" ||
+        plugin.marketplace !== "apex-plugins" ||
+        plugin.marketplaceRepository !== "jonathan-vella/apex-plugins" ||
+        !paths(plugin.ownedFiles) ||
+        !paths(plugin.ownedDirectories) ||
+        plugin.ownedDirectories.length === 0) {
+        throw new Error("Bundled plugin declaration is invalid");
+    }
+    return {
+        name: plugin.name,
+        marketplace: plugin.marketplace,
+        marketplaceRepository: plugin.marketplaceRepository,
+        ownedFiles: [...plugin.ownedFiles],
+        ownedDirectories: [...plugin.ownedDirectories],
+    };
+}
+/** True when the apex plugin, not the workspace projection, owns this workspace-relative path. */
+export function pluginOwnsPath(plugin, path) {
+    return (plugin.ownedFiles.includes(path) ||
+        plugin.ownedDirectories.some((directory) => path === directory || path.startsWith(`${directory}/`)));
+}
+/** Reads only the plugin declaration from the bundled manifest; full asset verification stays in resolveBundledAssets. */
+export async function readBundledPluginDeclaration() {
+    const root = fileURLToPath(new URL("../assets/", import.meta.url));
+    return pluginDeclaration(JSON.parse((await readBundledFile(root, "customizations/manifest.json")).toString("utf8")).plugin);
+}
 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);
+    const customizationManifest = JSON.parse((await readBundledFile(root, "customizations/manifest.json")).toString("utf8"));
     return {
         root: dirname(join(root, "manifest.json")),
         customizations: join(root, "customizations"),
+        plugin: pluginDeclaration(customizationManifest.plugin),
         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"),

package/dist/bootstrap-wizard.d.ts

@@ -0,0 +1,37 @@
+import { ApexService } from "./service.js";
+export interface BootstrapInteraction {
+    ask(question: string): Promise<string>;
+    show(value: unknown): void;
+}
+type SetupService = Pick<ApexService, "listArchetypes" | "planArchetypeBatch" | "importArchetypeBatch" | "planBootstrap" | "bootstrap" | "planRepositoryPublish" | "publishRepository" | "planGovernanceSetup" | "planGovernanceProvision" | "provisionGovernance" | "inspectGovernanceBaselineReadiness">;
+/** Runs one workspace's setup steps, for example while holding that workspace's lock. */
+export type BootstrapWorkspaceScope = <T>(directory: string, body: () => Promise<T>) => Promise<T>;
+export declare function runBootstrapWizard(root: string, interaction: BootstrapInteraction, serviceAt?: (directory: string) => SetupService, scope?: BootstrapWorkspaceScope): Promise<{
+    status: string;
+    progress: {
+        directory: string;
+        step: string;
+        outcome: unknown;
+    }[];
+    nextAction: string;
+}>;
+/**
+ * Runs the wizard on the terminal, or on `options.interaction` when given, while the command holds the workspace lock
+ * of `root` through `service`. Each copied workspace's steps also hold that workspace's own lock. Every question is
+ * asked without any of these locks, so MCP calls are not blocked while the wizard waits; if a workspace changed during
+ * the wait, the wizard fails with `APEX_STALE` instead of applying the answer.
+ */
+export declare function interactiveBootstrap(root: string, service: Pick<ApexService, "waitOutsideWorkspaceLock">, options?: {
+    interaction?: BootstrapInteraction | undefined;
+    serviceAt?: (directory: string) => ApexService;
+}): Promise<{
+    status: string;
+    progress: {
+        directory: string;
+        step: string;
+        outcome: unknown;
+    }[];
+    nextAction: string;
+}>;
+export {};
+//# sourceMappingURL=bootstrap-wizard.d.ts.map