@qodeca/xezar 0.13.0 → 0.14.0

package/dist/mcp/tools/project-config.d.ts

@@ -0,0 +1,340 @@
+import { z } from 'zod';
+import { type ServiceDispatch } from '../service-adapter.ts';
+import { type McpToolContext } from '../tool.ts';
+/**
+ * Project configuration for the bound project (#97, F-05, F-12, F-16; D-03 in
+ * `docs/features/mcp-server/mcp-settings-classification.md`, which this module implements and
+ * does not re-decide).
+ *
+ * THE BOUNDARY. A leader reads and writes THIS project's own settings, workflows, skills,
+ * automations and worktrees. Shared (workspace, machine, home) settings are served only as the
+ * effective capability or limit the classification names, with what it withholds withheld.
+ * Everything the classification marks `excluded` is an explicit action here that answers a
+ * refusal naming its boundary and dispatches NOTHING — so a leader asking for it learns why, and
+ * no argument can route around it. There is no project id argument anywhere: the project is the
+ * connection's (D-01 § 1.5), and a call that names one is refused rather than silently
+ * redirected.
+ *
+ * THE SAME RULES AS THE COCKPIT. Every effect is one of the cockpit's own routes, dispatched
+ * in-process under `/api/v1/p/<bound project>/…` through the same validators, 400/404/409
+ * answers and stores (N-02). Two of those guarantees are load-bearing and are deliberately NOT
+ * re-implemented here, because a second copy is how they would drift:
+ *   - `PUT /agent-config/:id` answers 409 whenever `capabilities().localHandoff` is false (it
+ *     closes a hooks-based remote-code-execution path). A write goes THROUGH that route, so the
+ *     409 applies to MCP exactly as to the cockpit;
+ *   - built-in workflows answer 400 on delete, `stepsIssue` refuses a bad chain, and a
+ *     `.xezar/workflows` file is written with `wx` unless `overwrite` says otherwise.
+ *
+ * WHAT THIS MODULE ADDS, all of it narrowing (the classification's § 7):
+ *   - E-SCOPE-USER: a catalog file whose `scope` is `'user'` is refused, read and write alike,
+ *     keyed off the CATALOG FIELD and never off a path. The refusal is identical whether or not
+ *     the file exists, so it is not an existence oracle;
+ *   - a catalog file that resolves OUTSIDE the project (an in-repo symlink into a home folder) is
+ *     refused too — the route writes through a symlink, and a project write must stay local in
+ *     effect (requirements § 8);
+ *   - an MCP-holding project file is read as STRUCTURE only (§ 4.2, ruling 12): key names and
+ *     value kinds, never a value;
+ *   - E-NARROW: the registry, the workspace settings, the account listing and the skills-update
+ *     state are reduced to the bound project's own facts before anything is returned;
+ *   - no action takes a command. A workflow is saved with agent steps only: a check step's
+ *     `command` is a shell command the service runs later, and F-08 / § 3 keep arbitrary
+ *     operating-system processes out of this surface (`execution-control.test.ts` pins it for
+ *     the whole registry). The cockpit's Import → Save can store one; through MCP it is refused,
+ *     never stripped;
+ *   - and the other half of that rule (F-22, #262): no action REMOVES a check step either. A
+ *     save that would overwrite or shadow an on-disk workflow holding one, and a delete of such a
+ *     workflow, are refused as a quality-gate blocker before anything is dispatched — refusing to
+ *     add a gate while allowing its removal would protect nothing;
+ *   - automations match the cockpit FORM, not the wider route contract (D-97, I-097, I-098):
+ *     create takes `name`, `prompt` and `enable` plus the form's fixed values, and update edits
+ *     `name` and `prompt` and carries everything else through, exactly as the edit form does.
+ *
+ * WHAT IS NEVER RETURNED: an account identity (email, organisation, plan — F-12, N-01), the
+ * launch key or any credential (F-15), another project's row, or an absolute path outside the
+ * project. Paths inside the project are reported relative to its root.
+ *
+ * WHERE THE SERVICE COMES FROM. `McpToolContext` does not carry the service's in-process entry
+ * yet (#86 shipped it without one). Like the sibling tools, this one reads it from an optional
+ * `service` field on the context and answers an honest tool error when it is absent.
+ */
+export type ProjectConfigContext = McpToolContext & {
+    readonly service?: ServiceDispatch;
+};
+/** Every action a leader may take. Each is one cockpit route (or a narrowed read of one). */
+export declare const PROJECT_CONFIG_ACTIONS: readonly ['get_config', 'set_config', 'get_project', 'set_project', 'get_prompt_templates', 'set_prompt_templates', 'get_limits', 'get_capabilities', 'get_account', 'list_agent_config', 'read_agent_config', 'write_agent_config', 'list_workflows', 'parse_workflow', 'save_workflow', 'delete_workflow', 'list_skills', 'get_skill', 'list_importable_skills', 'refresh_skills', 'check_skill_updates', 'list_automations', 'get_automation', 'create_automation', 'update_automation', 'delete_automation', 'enable_automation', 'pause_automation', 'check_automation', 'get_automation_check', 'get_automation_log', 'retry_automation_receipt', 'list_worktrees', 'reclaim_worktrees', 'remove_worktree'];
+export type ProjectConfigAction = (typeof PROJECT_CONFIG_ACTIONS)[number];
+/** The boundaries a refusal can name. Stable identifiers — the refusal's structured content
+ *  carries one, and the text names it. */
+export type ConfigBoundary = 'project-binding' | 'workspace-settings' | 'agent-accounts' | 'account-identity' | 'home-file' | 'outside-project' | 'host-filesystem' | 'host-process' | 'project-registry' | 'quality-gate' | 'secret';
+/**
+ * The `excluded` rows of the classification a leader might plausibly ask for, each answered with
+ * its boundary. None of them dispatches anything. Listed as actions (rather than left out of the
+ * enum) so the answer is an understandable reason, not a schema error.
+ */
+export declare const REFUSED_ACTIONS: {
+    readonly set_provider_enabled: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'turning a provider on or off changes it for every project on this machine. Read provider status with get_capabilities; a person changes it in the cockpit.';
+    };
+    readonly connect_provider: {
+        readonly boundary: 'host-process';
+        readonly reason: 'connecting a provider opens a login terminal on the host machine. A person does this in the cockpit.';
+    };
+    readonly retry_provider: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'clearing a provider authentication incident clears it for every project. Report the blocker instead; a person clears it in the cockpit.';
+    };
+    readonly create_account: {
+        readonly boundary: 'agent-accounts';
+        readonly reason: 'agent accounts are global and administered by a person, not by a project leader.';
+    };
+    readonly update_account: {
+        readonly boundary: 'agent-accounts';
+        readonly reason: 'agent accounts are global and administered by a person, not by a project leader.';
+    };
+    readonly remove_account: {
+        readonly boundary: 'agent-accounts';
+        readonly reason: 'agent accounts are global and administered by a person, not by a project leader.';
+    };
+    readonly select_account: {
+        readonly boundary: 'agent-accounts';
+        readonly reason: 'the account a project uses is stored with the global accounts. Read the effective account with get_account; a person changes it in the cockpit.';
+    };
+    readonly check_account_status: {
+        readonly boundary: 'agent-accounts';
+        readonly reason: 'probing one named account is global account administration. Provider status is in get_capabilities.';
+    };
+    readonly get_account_details: {
+        readonly boundary: 'account-identity';
+        readonly reason: 'account identity is never served to a project leader.';
+    };
+    readonly open_account_file: {
+        readonly boundary: 'host-process';
+        readonly reason: 'opening an account folder launches an application on the host machine.';
+    };
+    readonly set_workspace_config: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'workspace settings and limits apply to every project. Read the effective limits with get_limits; this project’s own settings are set_config and set_project.';
+    };
+    readonly set_workspace_ui_state: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'the workspace preference bag describes the person at the keyboard and is shared by every project.';
+    };
+    readonly browse_folders: {
+        readonly boundary: 'host-filesystem';
+        readonly reason: 'browsing folders lists host directories outside this project.';
+    };
+    readonly add_project: {
+        readonly boundary: 'project-registry';
+        readonly reason: 'registering projects manages the workspace, not this project.';
+    };
+    readonly clone_project: {
+        readonly boundary: 'project-registry';
+        readonly reason: 'cloning creates and registers a checkout outside this project.';
+    };
+    readonly remove_project: {
+        readonly boundary: 'project-registry';
+        readonly reason: 'removing a project deregisters it from the workspace and ends this connection’s binding.';
+    };
+    readonly apply_skill_updates: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'applying skill updates rewrites globally installed skills every project reads. check_skill_updates reports what is available.';
+    };
+    readonly import_skills: {
+        readonly boundary: 'workspace-settings';
+        readonly reason: 'the imported-skills list is a workspace-wide preference. list_skills shows this project’s effective catalog.';
+    };
+    readonly get_launch_key: {
+        readonly boundary: 'secret';
+        readonly reason: 'the launch key is a credential and never enters a tool response.';
+    };
+    readonly open_in_app: {
+        readonly boundary: 'host-process';
+        readonly reason: 'opening the project launches a desktop application on the host machine.';
+    };
+};
+export type RefusedAction = keyof typeof REFUSED_ACTIONS;
+export declare const projectConfigInputSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        add_project: "add_project";
+        apply_skill_updates: "apply_skill_updates";
+        browse_folders: "browse_folders";
+        check_account_status: "check_account_status";
+        check_automation: "check_automation";
+        check_skill_updates: "check_skill_updates";
+        clone_project: "clone_project";
+        connect_provider: "connect_provider";
+        create_account: "create_account";
+        create_automation: "create_automation";
+        delete_automation: "delete_automation";
+        delete_workflow: "delete_workflow";
+        enable_automation: "enable_automation";
+        get_account: "get_account";
+        get_account_details: "get_account_details";
+        get_automation: "get_automation";
+        get_automation_check: "get_automation_check";
+        get_automation_log: "get_automation_log";
+        get_capabilities: "get_capabilities";
+        get_config: "get_config";
+        get_launch_key: "get_launch_key";
+        get_limits: "get_limits";
+        get_project: "get_project";
+        get_prompt_templates: "get_prompt_templates";
+        get_skill: "get_skill";
+        import_skills: "import_skills";
+        list_agent_config: "list_agent_config";
+        list_automations: "list_automations";
+        list_importable_skills: "list_importable_skills";
+        list_skills: "list_skills";
+        list_workflows: "list_workflows";
+        list_worktrees: "list_worktrees";
+        open_account_file: "open_account_file";
+        open_in_app: "open_in_app";
+        parse_workflow: "parse_workflow";
+        pause_automation: "pause_automation";
+        read_agent_config: "read_agent_config";
+        reclaim_worktrees: "reclaim_worktrees";
+        refresh_skills: "refresh_skills";
+        remove_account: "remove_account";
+        remove_project: "remove_project";
+        remove_worktree: "remove_worktree";
+        retry_automation_receipt: "retry_automation_receipt";
+        retry_provider: "retry_provider";
+        save_workflow: "save_workflow";
+        select_account: "select_account";
+        set_config: "set_config";
+        set_project: "set_project";
+        set_prompt_templates: "set_prompt_templates";
+        set_provider_enabled: "set_provider_enabled";
+        set_workspace_config: "set_workspace_config";
+        set_workspace_ui_state: "set_workspace_ui_state";
+        update_account: "update_account";
+        update_automation: "update_automation";
+        write_agent_config: "write_agent_config";
+    }>;
+    projectId: z.ZodOptional<z.ZodUnknown>;
+    config: z.ZodOptional<z.ZodObject<{
+        baseBranch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        defaultRunner: z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            opencode: "opencode";
+            pi: "pi";
+        }>>;
+        systemPrompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        defaultModels: z.ZodOptional<z.ZodObject<{
+            claude: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            codex: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            opencode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+        memoryLimitMb: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        worktreeRetention: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        liveTitleUpdates: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        reviewGate: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        plannerModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        namerModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        skillsRepos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            repo: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strict>>;
+    project: z.ZodOptional<z.ZodObject<{
+        maxParallel: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        tags: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+    promptTemplates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        text: z.ZodString;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    fileId: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    yaml: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        overwrite: z.ZodOptional<z.ZodBoolean>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            runner: z.ZodOptional<z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                opencode: "opencode";
+                pi: "pi";
+            }>>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            bashAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            timeout: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    name: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    refresh: z.ZodOptional<z.ZodBoolean>;
+    automationId: z.ZodOptional<z.ZodString>;
+    automation: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        prompt: z.ZodString;
+        enable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    update: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+        expectedRevision: z.ZodNumber;
+    }, z.core.$strict>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        execute: "execute";
+        preview: "preview";
+    }>>;
+    checkId: z.ZodOptional<z.ZodString>;
+    receiptId: z.ZodOptional<z.ZodString>;
+    logQuery: z.ZodOptional<z.ZodObject<{
+        automationId: z.ZodOptional<z.ZodString>;
+        result: z.ZodOptional<z.ZodEnum<{
+            baseline: "baseline";
+            duplicate: "duplicate";
+            error: "error";
+            launched: "launched";
+            "no-match": "no-match";
+            preview: "preview";
+            "rate-limited": "rate-limited";
+        }>>;
+        event: z.ZodOptional<z.ZodEnum<{
+            "issue.labeled": "issue.labeled";
+            "issue.opened": "issue.opened";
+            "issue.unlabeled": "issue.unlabeled";
+            "pull_request.opened": "pull_request.opened";
+        }>>;
+        since: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    runId: z.ZodOptional<z.ZodString>;
+    expectedVersion: z.ZodOptional<z.ZodString>;
+    operationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProjectConfigInput = z.output<typeof projectConfigInputSchema>;
+/** The next legitimate action after a quality-gate refusal. It offers no waiver, to anyone (A-22). */
+export declare const QUALITY_GATE_NEXT_ACTION: string;
+/**
+ * Whether `path` really lands inside `root` once every symlink on the way is followed. The
+ * cockpit's writer goes THROUGH a symlink (`files.ts`), so an in-repo `.claude/settings.json`
+ * linked into a home folder would turn a project write into a home write. A path that does not
+ * exist yet is judged by its nearest existing ancestor — the directory the write would create it in.
+ */
+export declare function resolvesInside(root: string, path: string): boolean;
+type Shape = string | {
+    [key: string]: Shape;
+};
+/** Key names and value kinds down to `STRUCTURE_DEPTH`. Every scalar — command strings, args,
+ *  env values, headers, URLs, tokens — is reported as its kind (ruling 12, F-15). */
+export declare function structureOf(value: unknown, depth?: number): Shape;
+export declare const projectConfigTool: import("../tool.ts").McpTool<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>;
+export {};