/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2024 KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

syntax = "proto3";

package kiapi.common.commands;

import "common/types/base_types.proto";
import "common/types/project_settings.proto";


message GetNetClasses
{
}

message NetClassesResponse
{
  repeated kiapi.common.project.NetClass net_classes = 1;
}


message SetNetClasses
{
  repeated kiapi.common.project.NetClass net_classes = 1;

  // Whether to merge or replace the existing netclasses with the contents of this message
  // Note that this only happens at the level of netclass name: for example, if merge_mode is set to
  // MMM_MERGE, the design has netclasses ["Default", "HV"], and this message has netclasses
  // ["Default", "LV"], the resulting set will be ["Default", "HV", "LV"] -- the Default netclass
  // will have its properties replaced with those in this message, the "LV" netclass will be added,
  // and the "HV" netclass will be left alone.  If merge_mode is set to MMM_REPLACE, the "HV" class
  // will be erased.  Note that there must always be a "Default" netclass, so it will not be erased
  // even if merge_mode is MMM_REPLACE and there is no "Default" class specified in this message.
  kiapi.common.types.MapMergeMode merge_mode = 3;
}


/// Creates a new net class
message CreateNetClass
{
  kiapi.common.project.NetClass net_class = 1;
}

enum CreateNetClassStatus
{
  CNCS_UNKNOWN        = 0;
  CNCS_OK             = 1;  // Net class was created successfully
  CNCS_ALREADY_EXISTS = 2;  // A net class with this name already exists
  CNCS_INVALID_NAME   = 3;  // The net class name is invalid (empty or reserved)
}

message CreateNetClassResponse
{
  CreateNetClassStatus status = 1;
  string error_message = 2;
}


/// Deletes a net class by name
message DeleteNetClass
{
  string name = 1;  // Name of the net class to delete
}

enum DeleteNetClassStatus
{
  DNCS_UNKNOWN      = 0;
  DNCS_OK           = 1;  // Net class was deleted successfully
  DNCS_NOT_FOUND    = 2;  // Net class does not exist
  DNCS_CANNOT_DELETE_DEFAULT = 3;  // Cannot delete the "Default" net class
}

message DeleteNetClassResponse
{
  DeleteNetClassStatus status = 1;
  string error_message = 2;
}


message ExpandTextVariables
{
  kiapi.common.types.DocumentSpecifier document = 1;

  repeated string text = 2;
}


message ExpandTextVariablesResponse
{
  repeated string text = 1;
}


// returns kiapi.common.project.TextVariables
message GetTextVariables
{
  kiapi.common.types.DocumentSpecifier document = 1;
}


message SetTextVariables
{
  kiapi.common.types.DocumentSpecifier document = 1;

  kiapi.common.project.TextVariables variables = 2;
  // Whether to merge or replace the existing text variables map with the contents of this message
  kiapi.common.types.MapMergeMode merge_mode = 3;
}


/// A netclass pattern assignment (pattern -> netclass).
/// Stored at the project level in NET_SETTINGS.
message NetClassAssignment
{
  string pattern = 1;                    // Wildcard pattern to match net names
  string netclass = 2;                   // Netclass to assign
}


/// Gets all netclass pattern assignments
message GetNetClassAssignments
{
}

message GetNetClassAssignmentsResponse
{
  repeated NetClassAssignment assignments = 1;
}


/// Sets all netclass pattern assignments (replaces existing)
message SetNetClassAssignments
{
  repeated NetClassAssignment assignments = 1;
}


/// Launch an editor (schematic or PCB) via the project manager's KIWAY.
/// Editors launched this way run in non-standalone mode, enabling features like
/// pcb_sync_schematic that require both editors to share a project context.
/// Only handled by the project manager's API server.
message LaunchEditor
{
  kiapi.common.types.DocumentType doc_type = 1;
}

message LaunchEditorResponse
{
  bool already_open = 1;      // True if the editor was already open
  string socket_path = 2;     // API socket path of the launched editor
}


/// Retrieve the agent instructions (system prompt) from the C++ app.
/// Returns the core instructions markdown that is shared between the in-app agent
/// and the MCP server. Consumers append their own context-specific addendum.
/// Only handled by the project manager's API server.
message GetInstructions {}

message GetInstructionsResponse {
  string instructions_md = 1;   // Core instructions markdown content
}


/// Retrieve the tool manifest (schemas, script paths, metadata) from the C++ app.
/// The manifest is built at startup by TOOL_SCRIPT_LOADER and cached as JSON.
/// Only handled by the project manager's API server.
message GetToolSchemas {}

message GetToolSchemasResponse {
  string manifest_json = 1;      // JSON array of tool definitions
}


/// Execute an MCP tool through the C++ application's embedded Python executor.
/// Routes tool execution through HEADLESS_PYTHON_EXECUTOR with proper timeouts,
/// cancellation support, and optional transaction management (undo snapshots).
/// Only handled by the project manager's API server.
message ExecuteTool
{
  string tool_name = 1;          // Tool name, e.g. "sch_add", "pcb_place"
  string tool_args_json = 2;     // JSON-encoded tool arguments — C++ resolves app/script from manifest
  string app = 3;                // DEPRECATED: C++ resolves from manifest. Kept for wire compat.
  string script = 4;             // DEPRECATED: C++ resolves from manifest. Kept for wire compat.
}

message ExecuteToolResponse
{
  bool success = 1;
  string result_json = 2;     // JSON result from tool execution
  string error_message = 3;
}
