@ngocsangairvds/vsaf 3.2.11 → 3.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.2.11",
+  "version": "3.2.13",
   "description": "improve confluence format",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "superpowers"],
   "bin": {

package/src/global.js

@@ -140,10 +140,13 @@ async function setupVdsScriptsMcp() {
   ok('Đã sao chép vds-scripts.');
 
   info('Đang khởi tạo môi trường Python (uv sync)...');
-  if (!exec(`uv sync --frozen --project "${destDir}"`, { silent: true })) {
-    exec(`uv sync --project "${destDir}"`, { silent: true });
+  const syncOk = exec(`uv sync --frozen --package vds-cli --project "${destDir}"`, { silent: true })
+    || exec(`uv sync --package vds-cli --project "${destDir}"`, { silent: true });
+  if (syncOk) {
+    ok('Môi trường Python đã sẵn sàng.');
+  } else {
+    warn('uv sync thất bại — vds-cli có thể chưa sẵn sàng');
   }
-  ok('Môi trường Python đã sẵn sàng.');
 
   installVdsCliwrapper(destDir);
 
@@ -160,11 +163,13 @@ async function setupVdsScriptsMcp() {
     const jiraToken = await promptSecret('  Nhập JIRA_TOKEN: ');
     const confluenceToken = await promptSecret('  Nhập INTERNAL_CONFLUENCE_TOKEN: ');
     const extConfluenceToken = await promptSecret('  Nhập EXTERNAL_CONFLUENCE_TOKEN: ');
+    const vidpUsername = (await promptInput('  Nhập VDS_VIDP_USERNAME: '));
+    const vidpPassword = (await promptSecret('  Nhập VDS_VIDP_PASSWORD: '));
 
     const confluenceInternalUrl = (await promptInput('  Nhập CONFLUENCE_INTERNAL_URL (ex: http://10.254.136.35:8090): ')) || 'http://10.254.136.35:8090';
-    const confluenceExternalUrl = (await promptInput('  Nhập CONFLUENCE_EXTERNAL_URL (ex: https://atlassian.digital.vn): ')) || 'https://atlassian.digital.vn';
+    const confluenceExternalUrl = (await promptInput('  Nhập CONFLUENCE_EXTERNAL_URL (ex: https://atlassian.digital.vn): '));
 
-    const envContent = [
+    const envLines = [
       `VDS_USERNAME=${vdsUsername}`,
       `VDS_PASSWORD=${vdsPassword}`,
       `BITBUCKET_TOKEN=${bitbucketToken}`,
@@ -174,13 +179,17 @@ async function setupVdsScriptsMcp() {
       'JIRA_BASE_URL=https://jira.viettelmoney.vn/',
       `CONFLUENCE_INTERNAL_URL=${confluenceInternalUrl}`,
       `CONFLUENCE_EXTERNAL_URL=${confluenceExternalUrl}`,
-      'BITBUCKET_BASE_URL=http://bitbucket.digital.vn'
-    ].join('\n') + '\n';
+      'BITBUCKET_BASE_URL=http://bitbucket.digital.vn',
+      'VDS_VIDP_BASE_URL=http://cloud-idp.digital.vn/api/idp-gw',
+      `VDS_VIDP_USERNAME=${vidpUsername}`,
+      `VDS_VIDP_PASSWORD=${vidpPassword}`,
+    ];
 
-    fs.writeFileSync(envFile, envContent);
+    fs.writeFileSync(envFile, envLines.join('\n') + '\n');
     ok('Đã lưu cấu hình an toàn vào ~/.vds/.env');
   } else {
     ok('Đã tìm thấy file cấu hình ~/.vds/.env');
+    await ensureVidpEnv(envFile);
   }
 
   exec('claude mcp remove vds-orchestrator', { silent: true });
@@ -193,6 +202,33 @@ async function setupVdsScriptsMcp() {
   }
 }
 
+async function ensureVidpEnv(envFile) {
+  const current = fs.readFileSync(envFile, 'utf8');
+  if (/^\s*(VDS_)?VIDP_BASE_URL\s*=/m.test(current)) return;
+
+  const readKey = (key) => {
+    const match = current.match(new RegExp(`^\\s*${key}\\s*=\\s*(.*)$`, 'm'));
+    return match ? match[1].trim() : '';
+  };
+  const vdsUsername = readKey('VDS_USERNAME');
+  const vdsPassword = readKey('VDS_PASSWORD');
+
+  info('VIDP third-party gateway chưa được cấu hình — sẽ dùng VDS credentials (Enter để chấp nhận, nhập giá trị khác để override):');
+  const vidpUsername = (await promptInput(`  Nhập VDS_VIDP_USERNAME (Enter để dùng "${vdsUsername}"): `)) || vdsUsername;
+  const vidpPassword = (await promptSecret('  Nhập VDS_VIDP_PASSWORD (Enter để dùng VDS_PASSWORD): ')) || vdsPassword;
+
+  const suffix = [
+    '',
+    'VDS_VIDP_BASE_URL=http://cloud-idp.digital.vn/api/idp-gw',
+    `VDS_VIDP_USERNAME=${vidpUsername}`,
+    `VDS_VIDP_PASSWORD=${vidpPassword}`,
+    '',
+  ].join('\n');
+  const sep = current.endsWith('\n') ? '' : '\n';
+  fs.appendFileSync(envFile, sep + suffix);
+  ok('Đã thêm cấu hình VIDP vào ~/.vds/.env');
+}
+
 function promptInput(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

package/tools/skills/vds-scripts-skill/SKILL.md

@@ -78,6 +78,7 @@ vds-cli git --help
 - `vds-cli elastic ...`
 - `vds-cli grafana ...`
 - `vds-cli sonarqube ...`
+- `vds-cli vidp ...` — VIDP third-party gateway (trigger workflows, poll job status)
 
 ### Documentation and validation
 - `vds-cli openapi ...`

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/server.py

@@ -17,6 +17,7 @@ from .tools import (
     register_confluence_tools,
     register_git_tools,
     register_jira_tools,
+    register_vidp_tools,
 )
 
 # Initialize FastMCP server
@@ -51,6 +52,7 @@ register_jira_tools(mcp, execute_vds_cli)
 register_confluence_tools(mcp, execute_vds_cli)
 register_bitbucket_tools(mcp, execute_vds_cli)
 register_git_tools(mcp, execute_vds_cli)
+register_vidp_tools(mcp, execute_vds_cli)
 
 
 try:

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/__init__.py

@@ -4,10 +4,12 @@ from .bitbucket_tools import register_bitbucket_tools
 from .confluence_tools import register_confluence_tools
 from .git_tools import register_git_tools
 from .jira_tools import register_jira_tools
+from .vidp_tools import register_vidp_tools
 
 __all__ = [
     "register_bitbucket_tools",
     "register_confluence_tools",
     "register_git_tools",
     "register_jira_tools",
+    "register_vidp_tools",
 ]

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/vidp_tools.py

@@ -0,0 +1,64 @@
+"""VIDP tools for MCP server.
+
+Thin wrappers around ``vds-cli vidp ...`` so the VIDP gateway is reachable
+from any MCP client that talks to the ``vds-orchestrator`` server.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+
+def register_vidp_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register VIDP tools with the MCP server."""
+
+    @mcp.tool()
+    async def vidp_trigger(workflow: str, payload: Any | None = None) -> str:
+        """Trigger a VIDP third-party action by workflow UUID or alias.
+
+        Maps to ``POST /third-party/v2/start/{workflow_id}``.
+
+        Args:
+            workflow: VIDP workflow UUID (e.g. ``4afa9a1d-d36c-441a-b2fd-ba9612a854c1``)
+                OR a friendly alias defined in ``~/.vds/vidp-workflows.json``
+                (e.g. ``build-jenkins-by-job-name``). Aliases are case-insensitive.
+            payload: Optional JSON payload. Any JSON-serialisable object;
+                does not need to start with ``tenantToken``.
+
+        Returns:
+            JSON string with endpoint, alias used (if any), workflowId, request
+            payload, and full response.
+        """
+        args: list[str] = ["vidp", "trigger", workflow]
+        if payload is not None:
+            args.extend(["--payload", json.dumps(payload)])
+        result = await execute_cli(*args)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr'] or result['stdout']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def vidp_status(job_id: str, raw: bool = False) -> str:
+        """Get full workflow/stage detail for a VIDP job.
+
+        Maps to ``GET /third-party/v2/status/{job_id}?full=true``.
+
+        Args:
+            job_id: VIDP job id.
+            raw: If true, return only the raw VIDP response.
+
+        Returns:
+            JSON string with normalized job state and the raw VIDP response.
+        """
+        args: list[str] = ["vidp", "status", job_id]
+        if raw:
+            args.append("--raw")
+        result = await execute_cli(*args)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr'] or result['stdout']}"
+        return result["stdout"]

package/tools/vds-scripts/pyproject.toml

@@ -51,6 +51,7 @@ members = [
   # "telegram_bridge",  # disabled 2026-04-30 — aiogram 3.27 pydantic<2.13 vs memory-orchestrator pydantic>=2.13.3; restore when aiogram >=3.28.0 ships PR #1795
   "vds_sync_orchestrator",
   "text_utils_orchestrator",
+  "vidp_orchestrator",
 ]
 
 [tool.pytest.ini_options]

package/tools/vds-scripts/vds_cli/src/vds_cli/cli.py

@@ -451,6 +451,12 @@ def public_interface(ctx: typer.Context) -> None:
     _run_service("public_interface", list(ctx.args))
 
 
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def vidp(ctx: typer.Context) -> None:
+    """VIDP third-party gateway operations (trigger workflows, poll job status)."""
+    _run_service("vidp", list(ctx.args))
+
+
 @app.command(context_settings=PASS_THRU_CONTEXT)
 def scheduler(ctx: typer.Context) -> None:
     """Ecosystem scheduler operations (schedule/event/chain/workflow); requires VDS_SCHEDULER_ENABLED=true."""

package/tools/vds-scripts/vds_cli/src/vds_cli/router.py

@@ -175,6 +175,11 @@ ORCHESTRATORS = {
         "path": "public_interface_boundary_orchestrator",
         "entry": "vds-public-interface",
     },
+    "vidp": {
+        "module": "vds_vidp_orchestrator.cli",
+        "path": "vidp_orchestrator",
+        "entry": "vds-vidp",
+    },
     "scheduler": {
         "module": "vds_scheduler_orchestrator.cli",
         "path": "scheduler_orchestrator",

package/tools/vds-scripts/vidp_orchestrator/README.md

@@ -0,0 +1,31 @@
+# vds-vidp-orchestrator
+
+VIDP third-party gateway orchestrator for the VDS scripts ecosystem.
+
+Wraps two VIDP endpoints:
+
+- `POST /third-party/v2/start/{workflowId}` — trigger a workflow action
+- `GET /third-party/v2/status/{jobId}?full=true` — fetch full job/stage detail
+
+## Usage
+
+```bash
+# CLI
+vds-cli vidp trigger <workflowId> --payload '{"key":"value"}'
+vds-cli vidp status <jobId>
+
+# Direct
+uv run vds-vidp trigger <workflowId> --payload-file ./payload.json
+```
+
+## Environment
+
+Loaded from the shared VDS env file (`~/.vds/.env`). Settings use prefix
+`VDS_VIDP_` but legacy `VIDP_*` names are accepted as fallbacks.
+
+| Variable                          | Required | Notes                                  |
+| --------------------------------- | -------- | -------------------------------------- |
+| `VDS_VIDP_BASE_URL` / `VIDP_BASE_URL` | yes      | Base URL of the VIDP gateway           |
+| `VDS_VIDP_USERNAME` / `VIDP_USERNAME` | yes      | Basic-auth username                    |
+| `VDS_VIDP_PASSWORD` / `VIDP_PASSWORD` | yes      | Basic-auth password                    |
+| `VDS_VIDP_TIMEOUT_MS`             | no       | Request timeout in ms (default `30000`) |

package/tools/vds-scripts/vidp_orchestrator/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "vds-vidp-orchestrator"
+version = "0.1.0"
+description = "VDS VIDP Orchestrator — trigger third-party workflows and poll job status via VIDP gateway"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "VDS Team" }]
+keywords = ["vidp", "idp", "third-party", "vds", "orchestrator"]
+
+dependencies = [
+    "httpx>=0.28.1",
+    "typer>=0.24.1",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",
+    "structlog>=25.5.0",
+    "rich>=14.3.3",
+    "vds-cli-common",
+    "vds-platform-core",
+]
+
+[project.scripts]
+vds-vidp = "vds_vidp_orchestrator.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-httpx>=0.35.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.11.12",
+]
+
+[build-system]
+requires = ["hatchling>=1.20.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vds_vidp_orchestrator"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+vds_vidp_orchestrator = { workspace = true }
+vds-cli-common = { workspace = true }
+vds-platform-core = { workspace = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/__init__.py

@@ -0,0 +1,26 @@
+"""VDS VIDP Orchestrator package."""
+
+from vds_vidp_orchestrator.client import VidpClient
+from vds_vidp_orchestrator.config import VidpSettings, load_settings
+from vds_vidp_orchestrator.workflows import (
+    load_aliases,
+    load_package_aliases,
+    load_user_aliases,
+    package_workflows_file,
+    resolve_workflow_id,
+    save_user_aliases,
+    user_workflows_file,
+)
+
+__all__ = [
+    "VidpClient",
+    "VidpSettings",
+    "load_settings",
+    "load_aliases",
+    "load_package_aliases",
+    "load_user_aliases",
+    "package_workflows_file",
+    "user_workflows_file",
+    "resolve_workflow_id",
+    "save_user_aliases",
+]

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/cli.py

@@ -0,0 +1,246 @@
+"""CLI for the VIDP orchestrator.
+
+Examples:
+    vds-vidp trigger <workflowId>
+    vds-vidp trigger <workflowId> --payload '{"foo": "bar"}'
+    vds-vidp trigger <workflowId> --payload-file ./payload.json
+    vds-vidp status <jobId>
+    vds-vidp status <jobId> --raw
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from vds_cli_common.app import make_vds_app
+from vds_cli_common.context import CLIContext
+from vds_cli_common.output import OutputManager
+from vds_platform_core.errors import SettingsError
+from vds_platform_core.logging import configure_structlog
+
+from vds_vidp_orchestrator.client import VidpClient
+from vds_vidp_orchestrator.config import load_settings
+from vds_vidp_orchestrator.workflows import (
+    load_aliases,
+    load_package_aliases,
+    load_user_aliases,
+    package_workflows_file,
+    resolve_workflow_id,
+    save_user_aliases,
+    user_workflows_file,
+)
+
+configure_structlog()
+app = make_vds_app(
+    name="vds-vidp",
+    help="VDS VIDP CLI — trigger third-party workflows and poll job status.",
+    settings_factory=load_settings,
+)
+
+
+def _resolve_payload(payload: str | None, payload_file: Path | None) -> object | None:
+    if payload and payload_file:
+        raise typer.BadParameter("Use either --payload or --payload-file, not both.")
+    if payload:
+        try:
+            return json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise typer.BadParameter(f"--payload is not valid JSON: {exc}") from exc
+    if payload_file:
+        try:
+            return json.loads(payload_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise typer.BadParameter(f"--payload-file is not valid JSON: {exc}") from exc
+    return None
+
+
+@app.command()
+def trigger(
+    ctx: typer.Context,
+    workflow: Annotated[
+        str,
+        typer.Argument(
+            help="Workflow UUID OR alias from ~/.vds/vidp-workflows.json (e.g. 'build-jenkins-by-job-name').",
+        ),
+    ],
+    payload: Annotated[
+        str | None,
+        typer.Option("--payload", "-p", help="Inline JSON payload"),
+    ] = None,
+    payload_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--payload-file",
+            "-f",
+            exists=True,
+            readable=True,
+            dir_okay=False,
+            help="Path to a JSON file containing the payload",
+        ),
+    ] = None,
+) -> None:
+    """Trigger a VIDP third-party action by workflow id or alias."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        workflow_id, alias_used = resolve_workflow_id(workflow)
+        body = _resolve_payload(payload, payload_file)
+        settings = load_settings()
+        with VidpClient(settings) as client:
+            result = client.trigger(workflow_id, body)
+        out.output_json(
+            {
+                "tool": "vidp.trigger",
+                "endpoint": f"/third-party/v2/start/{workflow_id}",
+                "aliasUsed": alias_used,
+                "workflowId": workflow_id,
+                "requestPayload": body if body is not None else {},
+                "response": result,
+            }
+        )
+    except KeyError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1) from None
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}", hint="Check VDS_VIDP_* / VIDP_* env vars.")
+        raise typer.Exit(1) from None
+    except Exception as exc:  # noqa: BLE001 — surface as JSON for AI consumers
+        out.output_error(str(exc))
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def status(
+    ctx: typer.Context,
+    job_id: Annotated[
+        str,
+        typer.Argument(help="Job id (the {jobId} segment of the VIDP status endpoint)"),
+    ],
+    raw: Annotated[
+        bool,
+        typer.Option("--raw", help="Emit the raw VIDP response only (skip normalization)."),
+    ] = False,
+) -> None:
+    """Fetch full workflow/stage detail for a VIDP job."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        settings = load_settings()
+        with VidpClient(settings) as client:
+            response = client.status(job_id)
+        if raw:
+            out.output_json(response)
+            return
+        normalized = VidpClient.normalize_status(response)
+        out.output_json(
+            {
+                "tool": "vidp.status",
+                "endpoint": f"/third-party/v2/status/{job_id}?full=true",
+                "normalized": normalized,
+                "response": response,
+            }
+        )
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}", hint="Check VDS_VIDP_* / VIDP_* env vars.")
+        raise typer.Exit(1) from None
+    except Exception as exc:  # noqa: BLE001
+        out.output_error(str(exc))
+        raise typer.Exit(1) from None
+
+
+workflows_app = typer.Typer(
+    name="workflows",
+    help=(
+        "Manage workflow alias registry. Package defaults ship with vds-scripts "
+        "(read-only); add/remove writes to the user override file "
+        "(~/.vds/vidp-workflows.json or $VDS_VIDP_WORKFLOWS_FILE)."
+    ),
+)
+app.add_typer(workflows_app, name="workflows")
+
+
+@workflows_app.command("list")
+def workflows_list(ctx: typer.Context) -> None:
+    """List alias → workflow-id mappings, separated by source."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    package = load_package_aliases()
+    user = load_user_aliases()
+    overridden = {k for k in user if k in package and user[k] != package[k]}
+    out.output_json(
+        {
+            "packageFile": str(package_workflows_file()),
+            "userFile": str(user_workflows_file()),
+            "package": package,
+            "user": user,
+            "userOverridesPackage": sorted(overridden),
+            "merged": load_aliases(),
+        }
+    )
+
+
+@workflows_app.command("add")
+def workflows_add(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Alias name (e.g. 'build-jenkins-by-job-name')")],
+    workflow_id: Annotated[str, typer.Argument(help="Workflow UUID")],
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite if alias already exists in user file."),
+    ] = False,
+) -> None:
+    """Add or update an alias in the USER override file.
+
+    Package-shipped aliases are read-only; use ``--force`` to override them
+    locally via the user file.
+    """
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    user = load_user_aliases()
+    package = load_package_aliases()
+    if name in user and not force:
+        out.output_error(
+            f"Alias '{name}' already in user file → '{user[name]}'. Use --force to overwrite."
+        )
+        raise typer.Exit(1) from None
+    user[name] = workflow_id
+    path = save_user_aliases(user)
+    out.output_json(
+        {
+            "saved": str(path),
+            "alias": name,
+            "workflowId": workflow_id,
+            "overridesPackage": name in package and package[name] != workflow_id,
+        }
+    )
+
+
+@workflows_app.command("remove")
+def workflows_remove(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Alias name to remove from user file")],
+) -> None:
+    """Remove an alias from the USER override file.
+
+    Package-shipped aliases cannot be removed via CLI — edit the package
+    workflows.json directly to change the curated catalogue.
+    """
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    user = load_user_aliases()
+    if name not in user:
+        package = load_package_aliases()
+        if name in package:
+            out.output_error(
+                f"Alias '{name}' is shipped with the package (read-only). "
+                f"Edit {package_workflows_file()} to change it, or use "
+                f"'workflows add {name} <other-uuid> --force' to override locally."
+            )
+        else:
+            out.output_error(f"Alias '{name}' not found.")
+        raise typer.Exit(1) from None
+    removed = user.pop(name)
+    path = save_user_aliases(user)
+    out.output_json({"saved": str(path), "removed": name, "wasMappedTo": removed})
+
+
+if __name__ == "__main__":
+    app()

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/client.py

@@ -0,0 +1,104 @@
+"""HTTP client for the VIDP third-party gateway."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+import httpx
+from vds_platform_core.http.errors import map_http_error
+
+if TYPE_CHECKING:
+    from vds_vidp_orchestrator.config import VidpSettings
+
+
+class VidpClient:
+    """Thin synchronous client around the two VIDP endpoints we expose."""
+
+    def __init__(self, settings: VidpSettings) -> None:
+        self.settings = settings
+        self._client: httpx.Client | None = None
+
+    def _get_client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.settings.normalized_base_url,
+                headers={"Accept": "application/json", **self.settings.auth_header},
+                timeout=self.settings.timeout_seconds,
+            )
+        return self._client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+    ) -> dict[str, Any]:
+        client = self._get_client()
+        response = client.request(method, path, json=json_body)
+        try:
+            data: Any = response.json()
+        except ValueError:
+            data = {"raw": response.text}
+
+        if not response.is_success:
+            raise map_http_error(response.status_code, data, service="vidp")
+        return data if isinstance(data, dict) else {"data": data}
+
+    def trigger(self, workflow_id: str, payload: Any | None = None) -> dict[str, Any]:
+        """Trigger a third-party action by workflow id.
+
+        Mirrors ``POST /third-party/v2/start/{workflowId}``.
+        """
+        body = payload if payload is not None else {}
+        path = f"third-party/v2/start/{quote(workflow_id, safe='')}"
+        return self._request("POST", path, json_body=body)
+
+    def status(self, job_id: str) -> dict[str, Any]:
+        """Fetch full workflow/stage status for a VIDP job.
+
+        Mirrors ``GET /third-party/v2/status/{jobId}?full=true``.
+        """
+        path = f"third-party/v2/status/{quote(job_id, safe='')}?full=true"
+        return self._request("GET", path)
+
+    @staticmethod
+    def normalize_status(raw: dict[str, Any]) -> dict[str, Any]:
+        """Flatten the nested status response into the shape the original MCP returned."""
+        data = raw.get("data") or {}
+        workflows_raw = data.get("workflows") or []
+        workflows = []
+        for wf in workflows_raw:
+            steps = (wf or {}).get("steps") or {}
+            stages_raw = steps.get("stages") or []
+            workflows.append(
+                {
+                    "name": (wf or {}).get("name"),
+                    "status": (wf or {}).get("status"),
+                    "stepStatus": steps.get("status"),
+                    "stages": [
+                        {"name": (s or {}).get("name"), "status": (s or {}).get("status")}
+                        for s in stages_raw
+                    ],
+                }
+            )
+        return {
+            "jobName": data.get("name"),
+            "jobStatus": data.get("status"),
+            "workflows": workflows,
+        }
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> VidpClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+__all__ = ["VidpClient"]

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/config.py

@@ -0,0 +1,82 @@
+"""Strongly-typed VIDP settings using pydantic-settings.
+
+Loads from the shared VDS env file (~/.vds/.env) with prefix `VDS_VIDP_`.
+Accepts legacy `VIDP_*` env variables as aliases so existing VIDP MCP
+deployments keep working without re-configuring credentials.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any
+
+from pydantic import AliasChoices, Field, SecretStr, ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from vds_cli_common.env import load_shared_env
+from vds_platform_core.credentials import resolve_secret
+from vds_platform_core.errors import SettingsError
+
+
+class VidpSettings(BaseSettings):
+    """VIDP gateway settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=None,
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+        extra="ignore",
+        populate_by_name=False,
+    )
+
+    base_url: str = Field(
+        validation_alias=AliasChoices("VDS_VIDP_BASE_URL", "VIDP_BASE_URL"),
+        description="VIDP base URL (e.g. https://idp.example.com/)",
+    )
+    username: str = Field(
+        validation_alias=AliasChoices("VDS_VIDP_USERNAME", "VIDP_USERNAME"),
+        description="Basic-auth username",
+    )
+    password_secret: SecretStr = Field(
+        validation_alias=AliasChoices("VDS_VIDP_PASSWORD", "VIDP_PASSWORD"),
+        description="Basic-auth password",
+    )
+    timeout_ms: int = Field(
+        default=30_000,
+        ge=1,
+        validation_alias=AliasChoices("VDS_VIDP_TIMEOUT_MS", "VIDP_TIMEOUT_MS"),
+        description="HTTP request timeout in milliseconds",
+    )
+
+    @property
+    def password(self) -> str:
+        return resolve_secret(self.password_secret) or ""
+
+    @property
+    def timeout_seconds(self) -> float:
+        return self.timeout_ms / 1000.0
+
+    @property
+    def normalized_base_url(self) -> str:
+        return self.base_url.rstrip("/") + "/"
+
+    @property
+    def auth_header(self) -> dict[str, str]:
+        token = base64.b64encode(f"{self.username}:{self.password}".encode()).decode()
+        return {"Authorization": f"Basic {token}"}
+
+
+def load_settings(
+    *,
+    env_path: Path | None = None,
+    overrides: dict[str, Any] | None = None,
+) -> VidpSettings:
+    """Load VIDP settings from shared env + environment variables."""
+    load_shared_env(path=env_path)
+    try:
+        return VidpSettings(**(overrides or {}))
+    except ValidationError as exc:
+        raise SettingsError(str(exc)) from exc
+
+
+__all__ = ["VidpSettings", "load_settings", "SettingsError"]

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/workflows.json

@@ -0,0 +1,3 @@
+{
+  "build-jenkins-by-job-name": "4afa9a1d-d36c-441a-b2fd-ba9612a854c1"
+}

package/tools/vds-scripts/vidp_orchestrator/src/vds_vidp_orchestrator/workflows.py

@@ -0,0 +1,130 @@
+"""Workflow alias registry — map friendly names to VIDP workflow UUIDs.
+
+Two layers, merged at lookup time:
+
+1. **Package-shipped defaults** at ``<pkg>/workflows.json`` — curated by the
+   maintainer, distributed with the npm package, read-only at runtime.
+2. **User overrides** at ``~/.vds/vidp-workflows.json`` (or
+   ``$VDS_VIDP_WORKFLOWS_FILE``) — optional, user-editable, takes precedence
+   over package defaults. CLI ``add``/``remove`` only touch this file.
+
+``resolve_workflow_id()`` accepts a UUID or an alias and returns the canonical
+UUID. Alias lookup is case-insensitive.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+UUID_RE = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+
+
+def package_workflows_file() -> Path:
+    """Path to the package-shipped alias registry (read-only)."""
+    return Path(__file__).resolve().parent / "workflows.json"
+
+
+def user_workflows_file() -> Path:
+    """Path to the user-override alias registry (mutable; CLI writes here)."""
+    override = os.environ.get("VDS_VIDP_WORKFLOWS_FILE", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".vds" / "vidp-workflows.json"
+
+
+# Backwards-compatible name used by the CLI before the split.
+def workflows_file() -> Path:
+    """Deprecated alias for :func:`user_workflows_file`."""
+    return user_workflows_file()
+
+
+def _read_json(path: Path) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k).strip(): str(v).strip() for k, v in data.items() if isinstance(v, str)}
+
+
+def load_package_aliases() -> dict[str, str]:
+    """Aliases shipped with the package."""
+    return _read_json(package_workflows_file())
+
+
+def load_user_aliases() -> dict[str, str]:
+    """Aliases set by the user (override layer)."""
+    return _read_json(user_workflows_file())
+
+
+def load_aliases() -> dict[str, str]:
+    """Merged view: package defaults overlaid with user overrides."""
+    merged = load_package_aliases()
+    merged.update(load_user_aliases())
+    return merged
+
+
+def save_user_aliases(aliases: dict[str, str]) -> Path:
+    """Write the user-override registry, creating parent dir if needed."""
+    path = user_workflows_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(aliases, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return path
+
+
+# Backwards-compatible name used by older callers.
+def save_aliases(aliases: dict[str, str]) -> Path:
+    """Deprecated alias for :func:`save_user_aliases`."""
+    return save_user_aliases(aliases)
+
+
+def is_uuid(value: str) -> bool:
+    return bool(UUID_RE.match(value.strip()))
+
+
+def resolve_workflow_id(name_or_id: str) -> tuple[str, str | None]:
+    """Return ``(workflow_id, alias_used)``.
+
+    - UUID input → returned as-is with ``alias_used=None``.
+    - Otherwise look up case-insensitively in the merged registry.
+    - Raises ``KeyError`` with a helpful message if no match.
+    """
+    value = name_or_id.strip()
+    if is_uuid(value):
+        return value, None
+
+    aliases = load_aliases()
+    if value in aliases:
+        return aliases[value], value
+    lower_map = {k.lower(): (k, v) for k, v in aliases.items()}
+    if value.lower() in lower_map:
+        canonical, wf_id = lower_map[value.lower()]
+        return wf_id, canonical
+
+    raise KeyError(
+        f"No workflow id found for alias '{value}'. "
+        f"Maintainer can add it to {package_workflows_file()} "
+        f"(shipped with package); user can add a private alias via "
+        f"'vds-cli vidp workflows add {value} <uuid>' "
+        f"(writes to {user_workflows_file()})."
+    )
+
+
+__all__ = [
+    "package_workflows_file",
+    "user_workflows_file",
+    "workflows_file",  # backwards-compat
+    "load_package_aliases",
+    "load_user_aliases",
+    "load_aliases",
+    "save_user_aliases",
+    "save_aliases",  # backwards-compat
+    "is_uuid",
+    "resolve_workflow_id",
+]