fa-mcp-sdk 0.11.10 → 0.11.14

package/cli-template/.claude/skills/create-mcp-wizard/SKILL.md

@@ -185,7 +185,7 @@ with an auth error, surface it to the user; do not attempt API-token workarounds
 Collect GitLab credentials — prefer values already in the accompanying text, ask only for what's
 missing:
 
-- `baseUrl` — e.g. `https://gitlab.finam.ru/api/v4`
+- `baseUrl` — e.g. `https://gitlab.corp.com/api/v4`
 - `token` — GitLab private token with `api` scope
 - `group` — group name or full path (e.g. `mcp-servers` or `ai/mcp`), OR `groupId` numeric
 

package/cli-template/.claude/skills/create-mcp-wizard/scripts/gitlab-push.js

@@ -7,7 +7,7 @@
  * Finally runs `git init / add / commit / remote add / push -u origin <branch>`.
  *
  * Environment / flags:
- *   --base-url  <url>    (e.g. https://gitlab.finam.ru/api/v4) — required
+ *   --base-url  <url>    (e.g. https://gitlab.corp.com/api/v4) — required
  *   --token     <tok>    GitLab private token — required
  *   --group     <name>   Group name or full path (e.g. "mcp-servers") — required unless --group-id is given
  *   --group-id  <n>      Numeric group id — overrides --group lookup
@@ -54,7 +54,7 @@ function die (msg, code = 1) {
   process.exit(code);
 }
 
-if (!baseUrl)     die('Missing --base-url (or GITLAB_BASE_URL). Example: https://gitlab.finam.ru/api/v4');
+if (!baseUrl)     die('Missing --base-url (or GITLAB_BASE_URL). Example: https://gitlab.corp.com/api/v4');
 if (!token)       die('Missing --token (or GITLAB_TOKEN).');
 if (!projectName) die('Missing --name (project name).');
 if (!groupId && !groupArg) die('Missing --group or --group-id.');
@@ -154,4 +154,4 @@ function gitPush (remoteUrl) {
   } catch (e) {
     die(e.message);
   }
-})();
+})();

package/cli-template/.env.example

@@ -1,48 +1,48 @@
-# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
-SERVICE_NAME={{project.name}}
-# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
-# PRODUCT_NAME=
-
-NODE_ENV={{NODE_ENV}}
-# Used for PM2
-SERVICE_INSTANCE={{SERVICE_INSTANCE}}
-PM2_NAMESPACE={{PM2_NAMESPACE}}
-
-# Affects how the Consul service ID is formed - as a product or development ID
-NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
-
-DEBUG=config-info
-# Used for PM2 service configuration
-#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
-#│ id │ name                                                      │ namespace       │
-#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
-#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
-
-## DEBUG patterns ##
-# AP-UPDATER - consul/access-points-updater
-# fa-consul:reg | fa-consul:* - consul/cyclic-register
-# fa-consul:curl - consul/prepare-consul-api
-# token:auth         - authentication: which auth method matched, token parsing/validation outcome
-# mcp:tool           - tools/call: tool name + arguments in, response (text or JSON) out
-# mcp:resource       - resources/list and resources/read: URI in, body out
-# mcp:notification   - all incoming notifications/* (method + params)
-# mcp:prompt         - prompts/list and prompts/get: name/args in, messages out
-# mcp:*              - all four MCP channels above at once
-# mcp-handshake      - HTTP transport: per-request dump (method, id, session routing, protocol, auth, IP)
-# mcp-rpc            - HTTP transport: one-line summary of every successful JSON-RPC response
-#
-#(session-lifecycle events, the -32600 "no valid session" rejection and JSON-RPC errors log always)
-#
-# ========================================================================
-# AGENT TESTER - Built-in AI agent for testing MCP tools
-# ========================================================================
-# AGENT_TESTER_ENABLED=true
-# AGENT_TESTER_USE_AUTH=false
-# AGENT_TESTER_OPENAI_API_KEY=sk-...
-# AGENT_TESTER_OPENAI_BASE_URL=
-
-# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
-# TEST_MCP_SERVER_URL=
-
-# The directory to store test result logs
-TEST_RESULT_LOGS_DIR='_logs/mcp'
+# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
+SERVICE_NAME={{project.name}}
+# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
+# PRODUCT_NAME=
+
+NODE_ENV={{NODE_ENV}}
+# Used for PM2
+SERVICE_INSTANCE={{SERVICE_INSTANCE}}
+PM2_NAMESPACE={{PM2_NAMESPACE}}
+
+# Affects how the Consul service ID is formed - as a product or development ID
+NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
+
+DEBUG=config-info
+# Used for PM2 service configuration
+#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
+#│ id │ name                                                      │ namespace       │
+#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
+#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
+
+## DEBUG patterns ##
+# AP-UPDATER - consul/access-points-updater
+# fa-consul:reg | fa-consul:* - consul/cyclic-register
+# fa-consul:curl - consul/prepare-consul-api
+# token:auth         - authentication: which auth method matched, token parsing/validation outcome
+# mcp:tool           - tools/call: tool name + arguments in, response (text or JSON) out
+# mcp:resource       - resources/list and resources/read: URI in, body out
+# mcp:notification   - all incoming notifications/* (method + params)
+# mcp:prompt         - prompts/list and prompts/get: name/args in, messages out
+# mcp:*              - all four MCP channels above at once
+# mcp-handshake      - HTTP transport: per-request dump (method, id, session routing, protocol, auth, IP)
+# mcp-rpc            - HTTP transport: one-line summary of every successful JSON-RPC response
+#
+#(session-lifecycle events, the -32600 "no valid session" rejection and JSON-RPC errors log always)
+#
+# ========================================================================
+# AGENT TESTER - Built-in AI agent for testing MCP tools
+# ========================================================================
+# AGENT_TESTER_ENABLED=true
+# AGENT_TESTER_USE_AUTH=false
+# AGENT_TESTER_OPENAI_API_KEY=sk-...
+# AGENT_TESTER_OPENAI_BASE_URL=
+
+# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
+# TEST_MCP_SERVER_URL=
+
+# The directory to store test result logs
+TEST_RESULT_LOGS_DIR='_logs/mcp'

package/cli-template/FA-MCP-SDK-DOC/02-1-tools-and-api.md

@@ -172,6 +172,92 @@ asJsonError({ code: 'NOT_FOUND', key: 'X' });  // { structuredContent: {...},
 > for missing resources, convert those branches to `return formatToolError('Not found: ...')`. The
 > LLM will start surfacing "Such an issue does not exist" to the user instead of failing the call.
 
+### Normalizing upstream API errors
+
+The `isError` vs `throw` decision above is easy when the handler discovers the problem itself (a `null`
+issue). It is harder when the failure surfaces as a raw error thrown deep inside an HTTP client — a 404
+from the upstream API arrives as an Axios/`fetch` rejection, not as a clean `formatToolError`. Catching
+that in every handler is repetitive and easy to get wrong. The pattern below centralizes it in the single
+`catch` of `handleToolCall`, and implements standard
+[§13.4 "Mapping upstream errors"](./12-implementation-standard.md#134-mapping-upstream-downstream-api-errors).
+
+It has three pure steps — translate, classify, surface:
+
+```typescript
+import {
+  formatToolError, ToolExecutionError, ServerError, RateLimitedError,
+  UpstreamUnavailableError, ValidationError, ConflictError, ResourceNotFoundError, toStr,
+} from 'fa-mcp-sdk';
+
+// 1. TRANSLATE — convert a raw upstream HTTP error into a typed error class (no throw here).
+//    Map the upstream status onto the Appendix B error set instead of one opaque ServerError.
+function handleAxiosError(error: any, toolName: string): never {
+  const status = error?.response?.status;
+  const msg = extractUpstreamMessage(error?.response?.data) ?? error?.message ?? 'Unknown error';
+  const data = { toolName, status };                       // safe: no body, no headers, no stack
+
+  if (!status || status >= 502) throw new UpstreamUnavailableError(`Upstream unavailable: ${msg}`, data);
+  if (status === 400)           throw new ValidationError(`Invalid request: ${msg}`);
+  if (status === 404)           throw new ResourceNotFoundError(msg, data);
+  if (status === 409)           throw new ConflictError(`State conflict: ${msg}`, data);
+  if (status === 429) {
+    const retryAfter = parseInt(error?.response?.headers?.['retry-after'], 10) || 60;
+    throw new RateLimitedError(`Rate limited: ${msg}`, retryAfter);
+  }
+  // 401/403 and other 5xx — keep the upstream status in `data.status` so step 2 can recognize it.
+  throw new ServerError(`Upstream error (HTTP ${status}): ${msg}`, data);
+}
+
+// 2. NORMALIZE — turn ANY thrown value into a concrete Error, still WITHOUT throwing.
+//    A pure function lets the MCP path (may surface to the LLM) and a REST path (always throws)
+//    share one step.
+export function normalizeToolError(error: any, toolName: string): Error {
+  if (error instanceof ToolExecutionError || error instanceof ServerError ||
+      typeof error?.jsonRpcCode === 'number') {
+    return error;                                          // already a domain error
+  }
+  if (isAxiosError(error)) {
+    try { handleAxiosError(error, toolName); } catch (converted) { return converted as Error; }
+  }
+  return new ServerError(toStr(error), { toolName }, true); // catch-all, sanitized (no upstream status)
+}
+
+// 3. CLASSIFY — decide whether the model should SEE the message (isError) or get a thrown protocol error.
+export function isLlmVisibleError(error: any): boolean {
+  if (error instanceof RateLimitedError) return false;     // retry contract — keep -32003 thrown
+  if (error instanceof ToolExecutionError) return true;    // JQL/validation written for the model
+  if (typeof error?.jsonRpcCode === 'number') return true; // ValidationError/NotFound/Conflict/Upstream
+  if (error instanceof ServerError && error?.details?.status != null) return true; // upstream 401/403/5xx
+  return false;                                            // catch-all ServerError → "Internal error"
+}
+```
+
+Wire all three into the single `catch`, so every handler benefits without its own try/catch:
+
+```typescript
+} catch (error: any) {
+  const normalized = normalizeToolError(error, toolName);
+  if (isLlmVisibleError(normalized)) {
+    // The model reads the upstream reason ("Issue AITECH-123 does not exist") and self-corrects.
+    return formatToolError(normalized.message);
+  }
+  throw normalized;                                        // RateLimitedError / internal → protocol error
+}
+```
+
+Why this split matters:
+
+- A **404 raised by the upstream API** becomes `ResourceNotFoundError` (numeric `jsonRpcCode`), so
+  `isLlmVisibleError` returns `true` and the model gets `result.isError=true` — exactly like the manual
+  `formatToolError` branch in the previous section, but for an error it never saw directly.
+- **`RateLimitedError` stays thrown** as `-32003` with `retryAfter` — clients depend on that contract, so
+  it must not collapse into an `isError` text result.
+- A **catch-all `ServerError`** (no `details.status`) stays thrown and is sanitized by the SDK to
+  `Internal error` — its text may carry internal detail and MUST NOT reach the model (standard §13.3).
+
+> Keep `normalizeToolError` **pure** (never throws). A throwing normalizer forces every call site into its
+> own try/catch and defeats the point of centralizing the logic.
+
 ### Headers Access
 
 Headers are normalized to lowercase. Available in HTTP/SSE transports:

package/cli-template/FA-MCP-SDK-DOC/06-utilities.md

@@ -37,6 +37,26 @@ class MyError extends BaseMcpError {
 | `RateLimitedError` | `RATE_LIMITED` | `-32003` | 429 | Appendix B |
 | `TimeoutError` | `TIMEOUT` | `-32004` | 504 | Appendix B |
 | `PayloadTooLargeError` | `PAYLOAD_TOO_LARGE` | `-32005` | 413 | Appendix B |
+| `UpstreamUnavailableError` | `UPSTREAM_UNAVAILABLE` | `-32006` | 503 | Appendix B |
+| `ConflictError` | `CONFLICT` | `-32007` | 409 | Appendix B |
+
+### Mapping a Downstream API Status to a Typed Error
+
+When a tool proxies a downstream HTTP API, translate the upstream status into one of these classes instead
+of a single opaque `ServerError`. This gives the JSON-RPC layer a meaningful code and lets the surfacing
+logic (next) decide whether the model should see the message. This is standard §13.4; the end-to-end
+`normalizeToolError` / `isLlmVisibleError` / `formatToolError` pattern is in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+| Upstream HTTP                 | Throw                       | Surfaced to model as `isError`? |
+|-------------------------------|-----------------------------|---------------------------------|
+| 400                           | `ValidationError`           | yes                             |
+| 401 / 403                     | `ServerError` (status in data) | yes                          |
+| 404                           | `ResourceNotFoundError`     | yes                             |
+| 409                           | `ConflictError`             | yes                             |
+| 429                           | `RateLimitedError`          | no — thrown, keeps `retryAfter` |
+| 502 / 503 / 504 / no response | `UpstreamUnavailableError`  | yes                             |
+| other 5xx / unexpected        | `ServerError` (no status)   | no — thrown, sanitized          |
 
 ## Error Utilities
 

package/cli-template/FA-MCP-SDK-DOC/12-implementation-standard.md

@@ -2,9 +2,9 @@
 
 | Parameter                  | Value                              |
 |----------------------------|------------------------------------|
-| Version                    | 1.2                                |
+| Version                    | 1.3                                |
 | Status                     | Active                             |
-| Date                       | 2026-06-03                         |
+| Date                       | 2026-06-05                         |
 | Scope                      | All internal company MCP servers   |
 | Base MCP                   | MCP 2025-11-25                      |
 | Starter SDK (optional)     | `fa-mcp-sdk`                       |
@@ -13,7 +13,8 @@
 > This document is the English translation of the corporate implementation standard. It restates the
 > explicit MCP 2025-11-25 requirements plus the corporate Avatar / AI Platform profile in a single
 > self-contained document. Version 1.2 adds the side-effect tools and risk-level rules and fixes the
-> `-32007` error-code inconsistency.
+> `-32007` error-code inconsistency. Version 1.3 adds §13.4 on mapping upstream (downstream API) errors
+> to typed error classes and the rule for surfacing model-correctable errors via `result.isError=true`.
 
 ## Table of Contents
 
@@ -765,6 +766,50 @@ An error returned externally MUST NOT contain:
 - raw SQL/expression text with user data;
 - internal service names that are not part of the public contract.
 
+### 13.4. Mapping upstream (downstream API) errors
+
+This section is a corporate recommendation for servers that proxy a downstream HTTP API (Jira, GitLab, an
+internal microservice, etc.). It defines how a failed upstream call is translated into the two error types
+of §13.1 so that the model receives an actionable reason instead of one opaque `-32603 Internal error`.
+
+When a tool calls a downstream API, the server SHOULD translate the upstream HTTP status into the matching
+typed error class from [Appendix B](#appendix-b-error-codes) rather than collapsing every failure into a
+generic internal error. The recommended mapping is:
+
+| Upstream HTTP                     | Typed error class      | JSON-RPC | Returned to the model |
+| --------------------------------- | ---------------------- | -------- | --------------------- |
+| 400                               | `ValidationError`      | -32602   | `isError=true`        |
+| 401 / 403                         | `ServerError` (with upstream status in `data`) | -32000 | `isError=true` |
+| 404                               | `ResourceNotFoundError`| -32002   | `isError=true`        |
+| 409                               | `ConflictError`        | -32007   | `isError=true`        |
+| 429                               | `RateLimitedError`     | -32003   | thrown (see below)    |
+| 502 / 503 / 504 / no response     | `UpstreamUnavailableError` | -32006 | `isError=true`      |
+| other 5xx                         | `ServerError`          | -32000   | thrown                |
+
+The decision whether to surface an error to the model or to throw it follows three rules:
+
+- An error whose message is **safe to expose and actionable** — built from the structured upstream error
+  body, not from internal state — SHOULD be returned as a tool execution result with `result.isError=true`
+  (§9.4, §13.1). The model reads the upstream reason (for example `Issue AITECH-123 does not exist`) and
+  self-corrects instead of treating the call as a hard sandbox failure. A `404` raised by the downstream
+  API is the canonical case: it MUST reach the model as `result.isError=true`, not as a thrown protocol
+  error.
+- `-32003 Rate limited` MUST remain a **thrown** protocol error and MUST carry the `Retry-After` header /
+  `retryAfter` value (§14, Appendix B.3). It MUST NOT be flattened into an `isError` text result, because
+  clients rely on the numeric code and the retry hint to schedule a retry.
+- An internal failure with **no upstream status** (the catch-all wrapper around an unexpected exception)
+  MUST stay a thrown protocol error and MUST be sanitized per §13.3 — typically `-32603 Internal error`
+  with no stack trace and no secrets.
+
+A reference implementation of this pattern — a pure `normalizeToolError()` that converts any thrown value
+into a typed error without throwing, an `isLlmVisibleError()` predicate that applies the three rules above,
+and the `formatToolError()` call that surfaces the message — is documented in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+Whatever message is exposed (via `isError=true` or a thrown error) MUST still satisfy the §13.3
+prohibitions: the upstream error body is forwarded only after it has been reduced to its human-readable
+text, never as a raw payload that could carry internal paths, tokens, or stack traces.
+
 ## 14. Limits and protection
 
 Each server MUST document and enforce:

package/cli-template/package.json

@@ -58,7 +58,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.11.10"
+    "fa-mcp-sdk": "^0.11.14"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/dist/core/web/static/agent-tester/script.js

@@ -800,6 +800,22 @@ class McpAgentTester {
     }
 
     this.refreshToolListAppIcons();
+    this.applyAppModeVisibility();
+  }
+
+  /**
+   * Show the Inspector tab only while MCP Apps mode is ON. When the mode is
+   * turned off while the Inspector tab is active, fall back to the Chat tab so
+   * the user is not left on a hidden pane.
+   */
+  applyAppModeVisibility() {
+    const appEl = document.querySelector('.app');
+    if (appEl) {
+      appEl.classList.toggle('apps-mode-on', !!this.appMode);
+    }
+    if (!this.appMode && this.activeTab === 'inspector') {
+      this.switchTab('chat');
+    }
   }
 
   /**
@@ -1395,6 +1411,7 @@ class McpAgentTester {
       this.appModeToggle.addEventListener('change', () => this.handleAppModeToggle());
       this.updateAppModeToggleAvailability();
     }
+    this.applyAppModeVisibility();
 
     this.mcpConnectionForm.addEventListener('submit', (e) => this.handleMcpConnection(e));
 

package/dist/core/web/static/agent-tester/styles.css

@@ -1110,6 +1110,17 @@ body {
 .inspector-section {
   padding: 8px 14px 14px;
   border-bottom: 1px solid var(--border);
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* App Tools list gets the larger share; UI Resources the smaller. Both scroll. */
+.inspector-tools .inspector-section:nth-of-type(1) {
+  flex: 2 1 0;
+}
+
+.inspector-tools .inspector-section:nth-of-type(2) {
+  flex: 1 1 0;
 }
 
 .inspector-section h4 {
@@ -1259,8 +1270,11 @@ body {
 }
 
 /* Inspector tab visibility tied to MCP Apps mode */
-.app:not([data-active-tab]) .app-only-tab,
-.tabs-bar .app-only-tab {
+.app-only-tab {
+  display: none;
+}
+
+.app.apps-mode-on .app-only-tab {
   display: inline-flex;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fa-mcp-sdk",
   "productName": "FA MCP SDK",
-  "version": "0.11.10",
+  "version": "0.11.14",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",

package/cli-template/.gitlab-ci.yml

@@ -1,135 +0,0 @@
-stages:
-  - lint
-  - test-build
-  - build-image
-  - deploy
-
-# ── CI: Merge Request checks ──────────────────────────────────────
-
-.node-template: &node-template
-  image: node:22-alpine
-  tags:
-    - docker
-  before_script:
-    - yarn install --frozen-lockfile
-  cache:
-    key:
-      files:
-        - yarn.lock
-    paths:
-      - node_modules/
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-
-lint:
-  <<: *node-template
-  stage: lint
-  script:
-    - yarn lint
-
-test-build:
-  <<: *node-template
-  stage: test-build
-  script:
-    - yarn build
-
-# ── CD: Build Docker Image ────────────────────────────────────────
-
-build-image:
-  stage: build-image
-  image: docker:27
-  services:
-    - docker:27-dind
-  tags:
-    - docker
-  script:
-    - docker compose -f deploy/docker/docker-compose.yml up -d --build --force-recreate app
-  rules:
-    - if: '$CI_COMMIT_BRANCH == "master"'
-      when: manual
-
-# ── CD: Deploy ────────────────────────────────────────────────────
-# Замените <SERVER_TAG> на тег вашего сервера, <BRANCH> на целевую ветку,
-# <DEPLOY_DIR> на путь к проекту на сервере.
-
-# deploy_<instance>:
-#   stage: deploy
-#   tags:
-#     - <SERVER_TAG>
-#   variables:
-#     HOST_PORT: {{port}}
-#   environment:
-#     name: <instance>
-#   script:
-#     - docker compose -f deploy/docker/docker-compose.yml --env-file .env up -d --build --force-recreate app
-#     - |
-#       echo "Waiting for health check..."
-#       for i in $(seq 1 60); do
-#         if docker compose -f deploy/docker/docker-compose.yml exec -T app wget -q -O /dev/null http://localhost:{{port}}/health 2>/dev/null; then
-#           echo "Health check passed after ${i}s"
-#           break
-#         fi
-#         if [ "$i" -eq 60 ]; then
-#           echo "Health check failed after 60s"
-#           docker compose -f deploy/docker/docker-compose.yml logs --tail=50 app
-#           exit 1
-#         fi
-#         sleep 1
-#       done
-#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=50 app
-#   rules:
-#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
-#       when: manual
-
-# stop_<instance>:
-#   stage: deploy
-#   tags:
-#     - <SERVER_TAG>
-#   environment:
-#     name: <instance>
-#   script:
-#     - docker compose -f deploy/docker/docker-compose.yml down
-#   rules:
-#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
-#       when: manual
-
-# restart_<instance>:
-#   stage: deploy
-#   tags:
-#     - <SERVER_TAG>
-#   variables:
-#     HOST_PORT: {{port}}
-#   environment:
-#     name: <instance>
-#   script:
-#     - docker compose -f deploy/docker/docker-compose.yml --env-file .env restart app
-#     - |
-#       echo "Waiting for health check..."
-#       for i in $(seq 1 60); do
-#         if docker compose -f deploy/docker/docker-compose.yml exec -T app wget -q -O /dev/null http://localhost:{{port}}/health 2>/dev/null; then
-#           echo "Health check passed after ${i}s"
-#           break
-#         fi
-#         if [ "$i" -eq 60 ]; then
-#           echo "Health check failed after 60s"
-#           docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
-#           exit 1
-#         fi
-#         sleep 1
-#       done
-#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
-#   rules:
-#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
-#       when: manual
-
-# logs_<instance>:
-#   stage: deploy
-#   tags:
-#     - <SERVER_TAG>
-#   environment:
-#     name: <instance>
-#   script:
-#     - docker compose -f deploy/docker/docker-compose.yml logs --tail=100 app
-#   rules:
-#     - if: '$CI_COMMIT_BRANCH == "<BRANCH>"'
-#       when: manual

package/cli-template/deploy/gitlab-runner/.env.example

@@ -1,16 +0,0 @@
-# ── GitLab Runner version ─────────────────────────────────
-GITLAB_VERSION=v18.10.3
-HELPER_VERSION=v18.10.3
-
-# ── GitLab connection ─────────────────────────────────────
-GITLAB_URL=https://gitlab.finam.ru/
-RUNNER_TAGS={{project.name}},docker
-
-# ── Runner identity ──────────────────────────────────────
-RUNNER_NAME={{project.name}}
-RUNNER_TOKEN=
-
-# ── Project directory on host ─────────────────────────────
-# Absolute or relative path to the project root on the server.
-# Defaults to ../../ (two levels up from this directory).
-# PROJECT_DIR=/var/opt/node/{{project.name}}

package/cli-template/deploy/gitlab-runner/README.md

@@ -1,65 +0,0 @@
-# GitLab Runner Setup
-
-Docker-based GitLab Runner for CI/CD pipelines. Uses Docker executor with Docker-out-of-Docker (DooD) pattern.
-
-## How It Works
-
-1. `start.sh` validates `.env`, resolves `PROJECT_DIR`, starts the runner container
-2. `entrypoint.sh` substitutes variables in `config.toml.template` → `config.toml`, starts `gitlab-runner run`
-3. Runner registers with GitLab, listens for CI jobs matching its tags
-
-## Setup
-
-```bash
-# 1. Copy environment template
-cp .env.example .env
-
-# 2. Get runner token from GitLab UI:
-#    Settings → CI/CD → Runners → New project runner
-#    Set tags, then copy the token
-
-# 3. Fill .env with your token and settings
-# Required: GITLAB_URL, RUNNER_NAME, RUNNER_TOKEN
-
-# 4. Start the runner
-bash start.sh
-```
-
-## Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `GITLAB_VERSION` | yes | v18.10.3 | GitLab Runner Docker image version |
-| `HELPER_VERSION` | yes | v18.10.3 | GitLab Runner Helper image version |
-| `GITLAB_URL` | yes | — | GitLab instance URL |
-| `RUNNER_TAGS` | no | {{project.name}},docker | Comma-separated tags for job matching |
-| `RUNNER_NAME` | yes | — | Runner hostname and container name |
-| `RUNNER_TOKEN` | yes | — | Authentication token from GitLab UI |
-| `PROJECT_DIR` | no | ../../ | Absolute path to project on host |
-
-## Management Commands
-
-```bash
-# Start
-bash start.sh
-
-# View logs
-docker compose logs -f
-
-# Check status
-docker compose exec gitlab-runner gitlab-runner status
-
-# Stop
-docker compose down
-
-# Restart
-docker compose restart
-```
-
-## Infrastructure
-
-- **Network:** `gitlab-network` (bridge)
-- **DNS:** Corporate DNS servers (10.77.96.10, 10.77.196.10)
-- **Executor:** Docker with `docker:27` default image
-- **Volumes:** Docker socket, daemon.json, project directory, /cache
-- **Healthcheck:** `gitlab-runner status` every 60s

package/cli-template/deploy/gitlab-runner/config/config.toml.template

@@ -1,26 +0,0 @@
-concurrent = 2
-check_interval = 0
-shutdown_timeout = 0
-sentry_dsn = ""
-
-[session_server]
-  session_timeout = 1800
-
-[[runners]]
-  name = "__RUNNER_NAME__"
-  url = "__GITLAB_URL__"
-  token = "__RUNNER_TOKEN__"
-  executor = "docker"
-  tag_list = "__RUNNER_TAGS__"
-  [runners.docker]
-    tls_verify = false
-    image = "docker:27"
-    privileged = true
-    disable_entrypoint_overwrite = false
-    oom_kill_disable = false
-    disable_cache = false
-    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/etc/docker/daemon.json:/etc/docker/daemon.json", "__PROJECT_DIR__:__PROJECT_DIR__", "/cache"]
-    shm_size = 0
-    network_mtu = 0
-    pull_policy = ["if-not-present"]
-    helper_image = "gitlab/gitlab-runner-helper:__HELPER_VERSION__"

package/cli-template/deploy/gitlab-runner/docker-compose.yml

@@ -1,39 +0,0 @@
-name: {{project.name}}-runner
-
-services:
-  gitlab-runner:
-    image: gitlab/gitlab-runner:${GITLAB_VERSION}
-    hostname: ${RUNNER_NAME}
-    container_name: ${RUNNER_NAME}
-    environment:
-      - TZ=Europe/Moscow
-      - RUNNER_NAME=${RUNNER_NAME}
-      - RUNNER_TOKEN=${RUNNER_TOKEN}
-      - PROJECT_DIR=${PROJECT_DIR}
-      - GITLAB_URL=${GITLAB_URL}
-      - GITLAB_VERSION=${GITLAB_VERSION}
-      - RUNNER_TAGS=${RUNNER_TAGS}
-      - HELPER_VERSION=${HELPER_VERSION}
-    dns:
-      - 10.77.96.10
-      - 10.77.196.10
-    restart: always
-    entrypoint: ["/bin/sh", "/entrypoint.sh"]
-    volumes:
-      - './config:/etc/gitlab-runner'
-      - './entrypoint.sh:/entrypoint.sh:ro'
-      - '/var/run/docker.sock:/var/run/docker.sock'
-      - '/etc/docker/daemon.json:/etc/docker/daemon.json'
-    healthcheck:
-      test: ["CMD", "gitlab-runner", "status"]
-      interval: 1m
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-    networks:
-      - gitlab
-
-networks:
-  gitlab:
-    name: gitlab-network
-    driver: bridge

package/cli-template/deploy/gitlab-runner/entrypoint.sh

@@ -1,27 +0,0 @@
-#!/bin/sh
-set -e
-
-TEMPLATE="/etc/gitlab-runner/config.toml.template"
-CONFIG="/etc/gitlab-runner/config.toml"
-
-if [ -z "$RUNNER_TOKEN" ]; then
-  echo "ERROR: RUNNER_TOKEN is required" >&2
-  exit 1
-fi
-
-if [ -z "$PROJECT_DIR" ]; then
-  echo "ERROR: PROJECT_DIR is required" >&2
-  exit 1
-fi
-
-sed \
-  -e "s|__RUNNER_NAME__|${RUNNER_NAME}|g" \
-  -e "s|__RUNNER_TOKEN__|${RUNNER_TOKEN}|g" \
-  -e "s|__PROJECT_DIR__|${PROJECT_DIR}|g" \
-  -e "s|__RUNNER_TAGS__|${RUNNER_TAGS}|g" \
-  -e "s|__GITLAB_URL__|${GITLAB_URL}|g" \
-  -e "s|__GITLAB_VERSION__|${GITLAB_VERSION}|g" \
-  -e "s|__HELPER_VERSION__|${HELPER_VERSION}|g" \
-  "$TEMPLATE" > "$CONFIG"
-
-exec gitlab-runner run

package/cli-template/deploy/gitlab-runner/start.sh

@@ -1,47 +0,0 @@
-#!/bin/bash
-set -e
-cd "$(dirname "$0")"
-
-# Проверка наличия .env файла
-if [ ! -f .env ]; then
-    echo "ERROR: .env file not found in $(pwd)"
-    echo "Copy .env.example to .env and fill in the values:"
-    echo "  cp .env.example .env"
-    exit 1
-fi
-
-# Загружаем .env в текущий shell
-set -a
-. .env
-set +a
-
-# Проверка обязательных переменных
-required_vars=(
-    "GITLAB_URL"
-    "RUNNER_NAME"
-    "RUNNER_TOKEN"
-)
-missing=()
-for var in "${required_vars[@]}"; do
-    if [ -z "${!var}" ]; then
-        missing+=("$var")
-    fi
-done
-if [ ${#missing[@]} -gt 0 ]; then
-    echo "ERROR: Required variables not set in .env:"
-    for var in "${missing[@]}"; do
-        echo "  - $var"
-    done
-    exit 1
-fi
-
-# PROJECT_DIR: если не задан — два уровня вверх (корень проекта)
-if [ -z "$PROJECT_DIR" ]; then
-    PROJECT_DIR="../.."
-fi
-
-# Резолвим в абсолютный путь
-PROJECT_DIR=$(cd "$PROJECT_DIR" && pwd)
-export PROJECT_DIR
-
-exec docker compose up -d "$@"