baller-maester 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -59,6 +59,7 @@ declare const SourceSchema: z.ZodObject<{
         path: string;
         state?: "draft" | "canon" | undefined;
     })[] | undefined;
+    description?: string | undefined;
     ref?: string | undefined;
     auth?: {
         type: "none";
@@ -67,7 +68,6 @@ declare const SourceSchema: z.ZodObject<{
         envVar: string;
     } | undefined;
     destination?: string | undefined;
-    description?: string | undefined;
     tags?: string[] | undefined;
 }, {
     name: string;
@@ -76,6 +76,7 @@ declare const SourceSchema: z.ZodObject<{
         path: string;
         state?: "draft" | "canon" | undefined;
     })[] | undefined;
+    description?: string | undefined;
     ref?: string | undefined;
     auth?: {
         type: "none";
@@ -84,9 +85,56 @@ declare const SourceSchema: z.ZodObject<{
         envVar: string;
     } | undefined;
     destination?: string | undefined;
-    description?: string | undefined;
     tags?: string[] | undefined;
 }>;
+/**
+ * Per-connector entry in `CitadelConfig.connectors`. Per-type `config` payload
+ * is validated by the registered type's `configSchema` in `.superRefine` below.
+ */
+declare const ConnectorBaseSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    auth: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, "strict", z.ZodTypeAny, {
+        type: "none";
+    }, {
+        type: "none";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"token">;
+        envVar: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "token";
+        envVar: string;
+    }, {
+        type: "token";
+        envVar: string;
+    }>]>>;
+    description: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodUnknown>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    name: string;
+    description?: string | undefined;
+    auth?: {
+        type: "none";
+    } | {
+        type: "token";
+        envVar: string;
+    } | undefined;
+    config?: unknown;
+}, {
+    type: string;
+    name: string;
+    description?: string | undefined;
+    auth?: {
+        type: "none";
+    } | {
+        type: "token";
+        envVar: string;
+    } | undefined;
+    config?: unknown;
+}>;
 declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     baseDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
@@ -130,6 +178,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -138,7 +187,6 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }, {
         name: string;
@@ -147,6 +195,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -155,9 +204,52 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }>, "many">>>;
+    connectors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        auth: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"none">;
+        }, "strict", z.ZodTypeAny, {
+            type: "none";
+        }, {
+            type: "none";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"token">;
+            envVar: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            type: "token";
+            envVar: string;
+        }, {
+            type: "token";
+            envVar: string;
+        }>]>>;
+        description: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodUnknown>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }, {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }>, "many">>;
 }, "strict", z.ZodTypeAny, {
     sources: {
         name: string;
@@ -166,6 +258,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -174,10 +267,21 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }[];
     schemaVersion: 1;
+    connectors?: {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }[] | undefined;
     baseDir?: string | undefined;
 }, {
     schemaVersion: 1;
@@ -188,6 +292,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -196,9 +301,20 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }[] | undefined;
+    connectors?: {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }[] | undefined;
     baseDir?: string | undefined;
 }>, {
     sources: {
@@ -208,6 +324,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -216,10 +333,21 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }[];
     schemaVersion: 1;
+    connectors?: {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }[] | undefined;
     baseDir?: string | undefined;
 }, {
     schemaVersion: 1;
@@ -230,6 +358,7 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             path: string;
             state?: "draft" | "canon" | undefined;
         })[] | undefined;
+        description?: string | undefined;
         ref?: string | undefined;
         auth?: {
             type: "none";
@@ -238,13 +367,25 @@ declare const CitadelConfigSchema: z.ZodEffects<z.ZodObject<{
             envVar: string;
         } | undefined;
         destination?: string | undefined;
-        description?: string | undefined;
         tags?: string[] | undefined;
     }[] | undefined;
+    connectors?: {
+        type: string;
+        name: string;
+        description?: string | undefined;
+        auth?: {
+            type: "none";
+        } | {
+            type: "token";
+            envVar: string;
+        } | undefined;
+        config?: unknown;
+    }[] | undefined;
     baseDir?: string | undefined;
 }>;
 type AuthRef = z.infer<typeof AuthRefSchema>;
 type Source = z.infer<typeof SourceSchema>;
+type Connector = z.infer<typeof ConnectorBaseSchema>;
 type CitadelConfig = z.infer<typeof CitadelConfigSchema>;
 
 declare const PublishedDocumentSchema: z.ZodObject<{
@@ -255,14 +396,14 @@ declare const PublishedDocumentSchema: z.ZodObject<{
     state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
 }, "strict", z.ZodTypeAny, {
     path: string;
-    state?: "draft" | "canon" | undefined;
     description?: string | undefined;
+    state?: "draft" | "canon" | undefined;
     tags?: string[] | undefined;
     category?: string | undefined;
 }, {
     path: string;
-    state?: "draft" | "canon" | undefined;
     description?: string | undefined;
+    state?: "draft" | "canon" | undefined;
     tags?: string[] | undefined;
     category?: string | undefined;
 }>;
@@ -276,26 +417,26 @@ declare const MaesterConfigSchema: z.ZodObject<{
         state: z.ZodOptional<z.ZodEnum<["draft", "canon"]>>;
     }, "strict", z.ZodTypeAny, {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }, {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }>, "many">, {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }[], {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }[]>;
@@ -303,8 +444,8 @@ declare const MaesterConfigSchema: z.ZodObject<{
     schemaVersion: 1;
     documents: {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }[];
@@ -312,8 +453,8 @@ declare const MaesterConfigSchema: z.ZodObject<{
     schemaVersion: 1;
     documents: {
         path: string;
-        state?: "draft" | "canon" | undefined;
         description?: string | undefined;
+        state?: "draft" | "canon" | undefined;
         tags?: string[] | undefined;
         category?: string | undefined;
     }[];
@@ -446,6 +587,12 @@ type SkillInstallOutcome = {
     installedVersion?: string;
     error?: string;
 };
+type SkillMcpRegistrationOutcome = {
+    host: SkillTargetId;
+    filePath: string;
+    action: "written" | "unchanged" | "skipped" | "failed";
+    error?: string;
+};
 type SkillInstallResult = {
     outcomes: SkillInstallOutcome[];
     counts: {
@@ -454,6 +601,12 @@ type SkillInstallResult = {
         unchanged: number;
         failed: number;
     };
+    /**
+     * Per-host MCP server registration outcomes from the refresh step. Empty
+     * when no MCP-capable target is involved (e.g. install was scoped to
+     * `agents-md`) or when running an upgrade `--check`.
+     */
+    mcpRegistrations: SkillMcpRegistrationOutcome[];
 };
 type SkillStatusOutcomeState = "up-to-date" | "outdated" | "not-installed";
 type SkillStatusOutcome = {
@@ -487,7 +640,7 @@ type SkillTarget = {
     readonly label: string;
     /** Repo-relative paths this target writes. */
     readonly artifactPaths: readonly string[];
-    /** Writers backing different ids may share an implementation (codex + agents-md). */
+    /** Writers backing different ids may share an implementation; ids with distinct writerKeys produce separate file artifacts. */
     readonly writerKey: string;
     write(input: SkillWriteInput): Promise<SkillWriteOutcome>;
     /** Read the installed version marker from disk, if any. */
@@ -511,6 +664,197 @@ declare function runSkillStatus(repoRoot: string): Promise<SkillStatusResult>;
 
 declare const SKILL_VERSION: string;
 
+type ResolvedAuth = {
+    type: "delegated";
+} | {
+    type: "token";
+    value: string;
+    envVar: string;
+};
+
+declare const ENVELOPE_SCHEMA_VERSION: 1;
+type ConnectorErrorCode = "missing-env-var" | "connector-not-found" | "unknown-operation" | "invalid-argument" | "auth-failed" | "remote-error" | "internal-error";
+declare const CONNECTOR_ERROR_CODES: readonly ConnectorErrorCode[];
+/**
+ * Context passed to a connector operation handler. The dispatcher resolves the
+ * per-type config and auth before invocation; the handler never reads env vars
+ * or parses the raw connector entry.
+ */
+type ConnectorContext<TConfig = unknown> = {
+    /** Validated per-type config (already parsed by the type's configSchema). */
+    readonly config: TConfig;
+    /** Auth token value when the entry declared token auth; undefined otherwise. */
+    readonly token: string | undefined;
+    /** Resolved auth descriptor for handlers that need to know the mode. */
+    readonly auth: ResolvedAuth;
+};
+/**
+ * One operation exposed by a connector type. The same definition drives MCP
+ * tool registration (via argsSchema → JSON Schema) and runtime dispatch.
+ */
+type ConnectorOperation<TConfig = unknown, TArgs = unknown, TData = unknown> = {
+    /** Operation name, kebab-case (e.g. `list-issues`). */
+    readonly name: string;
+    /**
+     * Validates the operation's args object. Used for both runtime + inputSchema.
+     * The third generic is intentionally `unknown` so schemas with `.default()`
+     * or `.optional()` (where the input type differs from the output type) are
+     * accepted — the dispatcher always parses `unknown` input.
+     */
+    readonly argsSchema: z.ZodType<TArgs, z.ZodTypeDef, unknown>;
+    /** Per-type data shape version embedded in success payloads. */
+    readonly dataSchemaVersion: number;
+    /** Pure handler — receives validated args + context; returns `{ data }` or throws. */
+    readonly handler: (args: TArgs, ctx: ConnectorContext<TConfig>) => Promise<{
+        data: TData;
+    }>;
+};
+/**
+ * A connector type registered with the framework. The registry is the only
+ * place that imports per-type modules; everything else consults the registry.
+ *
+ * `operations` is intentionally an `any`-bounded record: each entry has its
+ * own concrete TArgs/TData via `defineConnectorOperation`, and the framework
+ * never touches the per-operation types directly — it routes through the
+ * operation's `argsSchema` for validation and its `handler` for execution.
+ */
+type AnyOperation<TConfig> = ConnectorOperation<TConfig, any, any>;
+type ConnectorType<TConfig = unknown> = {
+    /** Stable identifier used as the `type` value in citadel.yaml. */
+    readonly id: string;
+    /** Short human-readable name (e.g. "GitLab Issues"). */
+    readonly label: string;
+    /**
+     * Validates one connector entry's per-type config object. Input is
+     * intentionally `unknown` so schemas with `.default()` are accepted — the
+     * citadel-schema `.superRefine` always parses `unknown` config payloads.
+     */
+    readonly configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /** Map of operation name → operation definition. */
+    readonly operations: Readonly<Record<string, AnyOperation<TConfig>>>;
+    /**
+     * Returns the per-operation description rendered into `tools/list`. The
+     * framework prepends the connector entry's `description` (when set) — types
+     * do not do that composition themselves.
+     */
+    readonly describeTool: (operation: AnyOperation<TConfig>, resolvedConfig: TConfig) => string;
+};
+/**
+ * The success envelope shared by MCP tool results and the fallback CLI.
+ */
+type ConnectorSuccessEnvelope<TData = unknown> = {
+    readonly schema: typeof ENVELOPE_SCHEMA_VERSION;
+    readonly connector: string;
+    readonly operation: string;
+    readonly ok: true;
+    readonly data: TData & {
+        readonly dataSchema: number;
+    };
+};
+type ConnectorErrorPayload = {
+    readonly code: ConnectorErrorCode;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+};
+type ConnectorFailureEnvelope = {
+    readonly schema: typeof ENVELOPE_SCHEMA_VERSION;
+    readonly connector: string;
+    readonly operation: string;
+    readonly ok: false;
+    readonly error: ConnectorErrorPayload;
+};
+type ConnectorResultEnvelope<TData = unknown> = ConnectorSuccessEnvelope<TData> | ConnectorFailureEnvelope;
+/**
+ * Shape of a single MCP tool descriptor returned to clients during `tools/list`.
+ * The framework owns this composition; types provide pieces.
+ */
+type ConnectorToolDescriptor = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+};
+/**
+ * Helper for declaring an operation with TypeScript inference for args / data
+ * types — `ConnectorOperation` defaults the generics to `unknown`, which
+ * defeats inference at the call site. Use this in per-type modules instead of
+ * the bare object literal.
+ */
+declare function defineConnectorOperation<TConfig, TArgs, TData>(opts: {
+    name: string;
+    argsSchema: z.ZodType<TArgs, z.ZodTypeDef, unknown>;
+    dataSchemaVersion: number;
+    handler: (args: TArgs, ctx: ConnectorContext<TConfig>) => Promise<{
+        data: TData;
+    }>;
+}): ConnectorOperation<TConfig, TArgs, TData>;
+
+type InvokeOperationInput = {
+    /** The connector entry from `citadel.yaml` (already validated). */
+    connector: Connector;
+    /** Operation name as it appears on the type (kebab-case, e.g. "list-issues"). */
+    operationName: string;
+    /** Raw arguments object supplied by the caller (MCP `arguments` or CLI flags). */
+    args: unknown;
+    /** Optional environment override — defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * The only call path that runs a connector handler. Both the MCP server
+ * (`src/core/mcp/server.ts`) and the fallback CLI (`src/cli/commands/connector.ts`)
+ * go through it. Every outcome is wrapped in the documented envelope.
+ */
+declare function invokeOperation(input: InvokeOperationInput): Promise<ConnectorResultEnvelope>;
+/**
+ * Compose the human/agent-facing description for a single connector operation.
+ * Per Gap 48: if the entry carries a `description`, prepend it (trimmed) with
+ * a single space separator; otherwise return the type's description alone.
+ */
+declare function buildToolDescription(connector: Connector, operation: ConnectorOperation, resolvedConfig: unknown, type: ConnectorType): string;
+/**
+ * Build the full `tools/list` descriptor set from a validated citadel config.
+ * Used by both the MCP server (live) and `maester connector list` (debug).
+ *
+ * Configs with unknown connector types or per-type config validation failures
+ * are surfaced as `Error` throws — the citadel schema's `.superRefine` should
+ * have caught these at load time; reaching this function with an unknown type
+ * means a registry mutation happened after load.
+ */
+declare function listConnectorTools(config: CitadelConfig): ConnectorToolDescriptor[];
+/**
+ * Helper: find a connector and operation by their `(connectorName, operationName)`
+ * pair without dispatching. Used by the MCP server's `tools/call` handler to
+ * resolve the tool name back to a connector before invoking it.
+ *
+ * Returns `undefined` when either side is unknown — callers turn that into the
+ * appropriate `connector-not-found` / `unknown-operation` envelope.
+ */
+declare function findOperationByToolName(config: CitadelConfig, candidateToolName: string): {
+    connector: Connector;
+    operationName: string;
+    type: ConnectorType;
+} | undefined;
+
+declare function listConnectorTypes(): ConnectorType<unknown>[];
+declare function lookupConnectorType(id: string): ConnectorType<unknown> | undefined;
+declare function hasConnectorType(id: string): boolean;
+/**
+ * Add a type to the production registry. Called once per type from a per-type
+ * module's top-level import effect (e.g. `src/core/connectors/types/<id>/index.ts`).
+ * Re-registering the same id throws — type identifiers are write-once.
+ */
+declare function registerConnectorType<T>(type: ConnectorType<T>): void;
+
+/**
+ * Error thrown by connector handlers to signal a known failure mode. The
+ * dispatcher catches it and wraps it in the documented error envelope. Any
+ * other exception is treated as `internal-error`.
+ */
+declare class ConnectorError extends Error {
+    readonly code: ConnectorErrorCode;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: ConnectorErrorCode, message: string, details?: Record<string, unknown>);
+}
+
 declare class MaesterError extends Error {
     readonly code: string;
     readonly cause?: unknown;
@@ -543,4 +887,4 @@ declare class DestinationBlockedError extends MaesterError {
     constructor(destination: string, message: string);
 }
 
-export { AuthError, type AuthRef, type BehindReason, type CitadelConfig, ConfigError, DestinationBlockedError, type MaesterConfig, MaesterError, type ProgressEvent, type PublishedDocument, RefNotFoundError, SKILL_VERSION, type SkillAction, type SkillInstallOutcome, type SkillInstallResult, type SkillStatusOutcome, type SkillStatusResult, type SkillTarget, type SkillTargetId, type Source, type StatusCounts, type StatusOptions, type StatusOutcome, type StatusResult, type StatusVerdict, type SyncOptions, type SyncOutcome, type SyncResult, type SyncStatus, listSkillTargets, loadCitadelConfig, loadMaesterConfig, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };
+export { AuthError, type AuthRef, type BehindReason, CONNECTOR_ERROR_CODES, type CitadelConfig, ConfigError, type Connector, type ConnectorContext, ConnectorError, type ConnectorErrorCode, type ConnectorErrorPayload, type ConnectorFailureEnvelope, type ConnectorOperation, type ConnectorResultEnvelope, type ConnectorSuccessEnvelope, type ConnectorToolDescriptor, type ConnectorType, DestinationBlockedError, ENVELOPE_SCHEMA_VERSION, type MaesterConfig, MaesterError, type ProgressEvent, type PublishedDocument, RefNotFoundError, SKILL_VERSION, type SkillAction, type SkillInstallOutcome, type SkillInstallResult, type SkillStatusOutcome, type SkillStatusResult, type SkillTarget, type SkillTargetId, type Source, type StatusCounts, type StatusOptions, type StatusOutcome, type StatusResult, type StatusVerdict, type SyncOptions, type SyncOutcome, type SyncResult, type SyncStatus, buildToolDescription, defineConnectorOperation, findOperationByToolName, hasConnectorType, invokeOperation, listConnectorTools, listConnectorTypes, listSkillTargets, loadCitadelConfig, loadMaesterConfig, lookupConnectorType, registerConnectorType, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };