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

package/dist/mcp-tool-effects.d.ts

@@ -0,0 +1,101 @@
+import type { MCP_OUTPUT_SCHEMAS } from "./mcp-output-schemas.js";
+export type McpToolName = keyof typeof MCP_OUTPUT_SCHEMAS;
+/**
+ * Effect class of every MCP tool, keyed by the output-schema registry so a new tool cannot be added unclassified.
+ * - `read-only`: never writes state.
+ * - `read`: adds no new effect; it may only finish recovering an already-committed run or customization transaction,
+ *   so it holds the workspace lock like every other writer. While a CLI command holds the lock only to wait for an
+ *   external process, such as a provider preview or apply, it is answered from a validated snapshot without the lock
+ *   instead, and waits for the lock when it would need to recover.
+ * - `repeat-guarded`: changes state; each call runs through the kernel repeat guard, so an identical repeat while the
+ *   selected run is unchanged returns the original result instead of executing again.
+ * - `convergent`: changes state outside the run, so the run-scoped guard cannot tell whether a repeat is stale, and
+ *   converges on its own: `doctor` re-applies the same repair to workspace installation files, and
+ *   `improvementObserve` content-addresses observations, so a repeat returns the stored observation as deduplicated
+ *   or recreates it after a supported deletion.
+ */
+export type McpToolEffect = "read-only" | "read" | "repeat-guarded" | "convergent";
+export declare const MCP_TOOL_EFFECTS: {
+    readonly status: "read-only";
+    readonly projectList: "read-only";
+    readonly doctorChecks: "read";
+    readonly capabilityList: "read";
+    readonly capabilityStatus: "read";
+    readonly taskContext: "read";
+    readonly readTaskInput: "read";
+    readonly preview: "read";
+    readonly inventory: "read";
+    readonly diagnose: "read";
+    readonly render: "read";
+    readonly improvementObservations: "read";
+    readonly improvementProposals: "read";
+    readonly releaseWriter: "repeat-guarded";
+    readonly nextTask: "repeat-guarded";
+    readonly recordInput: "repeat-guarded";
+    readonly governanceImport: "repeat-guarded";
+    readonly governanceSelect: "repeat-guarded";
+    readonly projectCreate: "repeat-guarded";
+    readonly projectUse: "repeat-guarded";
+    readonly projectDelete: "repeat-guarded";
+    readonly gateDecide: "repeat-guarded";
+    readonly reviewDecide: "repeat-guarded";
+    readonly stageArtifact: "repeat-guarded";
+    readonly stageFile: "repeat-guarded";
+    readonly generateIac: "repeat-guarded";
+    readonly validateTask: "repeat-guarded";
+    readonly completeTask: "repeat-guarded";
+    readonly requirementsComplete: "repeat-guarded";
+    readonly architectureComplete: "repeat-guarded";
+    readonly reviewComplete: "repeat-guarded";
+    readonly planComplete: "repeat-guarded";
+    readonly reconcile: "repeat-guarded";
+    readonly promote: "repeat-guarded";
+    readonly submitEvidence: "repeat-guarded";
+    readonly improvementObserve: "convergent";
+    readonly doctor: "convergent";
+};
+/** Tools that change state: the `repeat-guarded` and `convergent` effect classes. */
+export type McpStateChangingTool = {
+    [Name in McpToolName]: (typeof MCP_TOOL_EFFECTS)[Name] extends "repeat-guarded" | "convergent" ? Name : never;
+}[McpToolName];
+/**
+ * Pending-review guard of every state-changing tool (DECISION-031 amendment of 2026-10-08), so a new state-changing
+ * tool cannot be added without deciding. Rubber-duck inherits the caller's APEX tools and the managed hooks fail open
+ * when missing or timed out, so while a review waits for its capture, the service refuses each operation marked
+ * `approve`, `delete` or `publish` with APEX_REVIEW_PENDING, on MCP and on the CLI command for the same operation.
+ * `null` leaves the tool to its usual kernel checks: task flow, staging, the review's own `reviewComplete`, project
+ * creation and selection, governance import, reconciliation and the convergent installation and observation tools.
+ * CLI-only commands are outside this table: they need a terminal, which neither the APEX agent nor rubber-duck has.
+ */
+export type ReviewGuard = "approve" | "delete" | "publish";
+export declare const MCP_TOOL_REVIEW_GUARDS: {
+    readonly releaseWriter: null;
+    readonly nextTask: null;
+    readonly recordInput: "approve";
+    readonly governanceImport: null;
+    readonly governanceSelect: null;
+    readonly projectCreate: null;
+    readonly projectUse: null;
+    readonly projectDelete: "delete";
+    readonly gateDecide: "approve";
+    readonly reviewDecide: "approve";
+    readonly stageArtifact: null;
+    readonly stageFile: null;
+    readonly generateIac: null;
+    readonly validateTask: null;
+    readonly completeTask: null;
+    readonly requirementsComplete: null;
+    readonly architectureComplete: null;
+    readonly reviewComplete: null;
+    readonly planComplete: null;
+    readonly reconcile: null;
+    readonly promote: "publish";
+    readonly submitEvidence: "publish";
+    readonly improvementObserve: null;
+    readonly doctor: null;
+};
+/** Tools the pending-review guard refuses. */
+export type ReviewGuardedTool = {
+    [Name in McpStateChangingTool]: (typeof MCP_TOOL_REVIEW_GUARDS)[Name] extends ReviewGuard ? Name : never;
+}[McpStateChangingTool];
+//# sourceMappingURL=mcp-tool-effects.d.ts.map

package/dist/mcp-tool-effects.js

@@ -0,0 +1,66 @@
+export const MCP_TOOL_EFFECTS = {
+    status: "read-only",
+    projectList: "read-only",
+    doctorChecks: "read",
+    capabilityList: "read",
+    capabilityStatus: "read",
+    taskContext: "read",
+    readTaskInput: "read",
+    preview: "read",
+    inventory: "read",
+    diagnose: "read",
+    render: "read",
+    improvementObservations: "read",
+    improvementProposals: "read",
+    releaseWriter: "repeat-guarded",
+    nextTask: "repeat-guarded",
+    recordInput: "repeat-guarded",
+    governanceImport: "repeat-guarded",
+    governanceSelect: "repeat-guarded",
+    projectCreate: "repeat-guarded",
+    projectUse: "repeat-guarded",
+    projectDelete: "repeat-guarded",
+    gateDecide: "repeat-guarded",
+    reviewDecide: "repeat-guarded",
+    stageArtifact: "repeat-guarded",
+    stageFile: "repeat-guarded",
+    generateIac: "repeat-guarded",
+    validateTask: "repeat-guarded",
+    completeTask: "repeat-guarded",
+    requirementsComplete: "repeat-guarded",
+    architectureComplete: "repeat-guarded",
+    reviewComplete: "repeat-guarded",
+    planComplete: "repeat-guarded",
+    reconcile: "repeat-guarded",
+    promote: "repeat-guarded",
+    submitEvidence: "repeat-guarded",
+    improvementObserve: "convergent",
+    doctor: "convergent",
+};
+export const MCP_TOOL_REVIEW_GUARDS = {
+    releaseWriter: null,
+    nextTask: null,
+    recordInput: "approve",
+    governanceImport: null,
+    governanceSelect: null,
+    projectCreate: null,
+    projectUse: null,
+    projectDelete: "delete",
+    gateDecide: "approve",
+    reviewDecide: "approve",
+    stageArtifact: null,
+    stageFile: null,
+    generateIac: null,
+    validateTask: null,
+    completeTask: null,
+    requirementsComplete: null,
+    architectureComplete: null,
+    reviewComplete: null,
+    planComplete: null,
+    reconcile: null,
+    promote: "publish",
+    submitEvidence: "publish",
+    improvementObserve: null,
+    doctor: null,
+};
+//# sourceMappingURL=mcp-tool-effects.js.map

package/dist/mcp.d.ts

@@ -1,5 +1,52 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server } from "@modelcontextprotocol/server";
+import type { Readable, Writable } from "node:stream";
 import { ApexService } from "./service.js";
-export declare function createMcpServer(service: ApexService): McpServer;
-export declare function serveMcp(service: ApexService): Promise<void>;
+export declare const MCP_SERVER_INSTRUCTIONS: string;
+export declare const MCP_MAX_SERIALIZED_RESULT_BYTES: number;
+export interface McpServiceResolver {
+    defaultService: ApexService;
+    resolve(workspace: string): Promise<{
+        service: ApexService;
+        workspace: string;
+    }>;
+}
+export { MCP_TOOL_EFFECTS, MCP_TOOL_REVIEW_GUARDS, type McpToolEffect } from "./mcp-tool-effects.js";
+/** Tools in the `read-only` effect class. Every other APEX tool is state-changing, which the rubber-duck deny hook enforces. */
+export declare const MCP_READ_ONLY_TOOLS: ReadonlySet<string>;
+/**
+ * The tool effect policy the plugin build ships beside the managed hooks (apex-mcp-tools.json), so the rubber-duck deny
+ * hook and the MCP annotations share one source.
+ */
+export declare function mcpToolPolicy(): {
+    server: "apex";
+    tools: string[];
+    readOnly: string[];
+};
+type DoctorReport = Awaited<ReturnType<ApexService["doctor"]>>;
+/**
+ * Bounds a doctor report for MCP. Failing checks come first, then passing checks other than per-file `managed:`
+ * hashes; every check left out is counted in `omitted`, and doctorChecks pages the complete list. Remedies are
+ * deduplicated, so no distinct remedy is dropped. CLI output keeps the full report.
+ */
+export declare function summarizeDoctorReport(report: DoctorReport): Record<string, unknown>;
+export interface McpServerOptions {
+    queueTimeoutMs?: number;
+}
+/**
+ * Builds the APEX MCP tool table and shared call state once, and returns a cheap, side-effect-free factory for
+ * low-level SDK `Server` instances. Every instance from one factory shares the service resolver, single-slot queue,
+ * rate limit, and cursor secret, so per-connection (stdio) and per-request (HTTP) instances behave as one server.
+ */
+export declare function createMcpServerFactory(serviceOrResolver: ApexService | McpServiceResolver, options?: McpServerOptions): () => Server;
+export declare function createMcpServer(serviceOrResolver: ApexService | McpServiceResolver, options?: McpServerOptions): Server;
+/**
+ * Serves APEX over stdio until the connection ends (stdin EOF), the transport fails, or SIGINT/SIGTERM arrives.
+ * `serveStdio` answers `server/discover` for protocol 2026-07-28 and, with `legacy: "serve"`, still serves a 2025-era
+ * `initialize` (including the discover-then-initialize fallback) from the same factory. Stdout stays protocol-only.
+ * A stdin error closes the connection and rejects. `streams` defaults to the process stdio.
+ */
+export declare function serveMcp(serviceOrResolver: ApexService | McpServiceResolver, streams?: {
+    stdin?: Readable;
+    stdout?: Writable;
+}): Promise<void>;
 //# sourceMappingURL=mcp.d.ts.map