@adinsure-ops/ops-cli 5.4.2 → 5.5.0-rc1

package/README.md

@@ -8,21 +8,156 @@ Operations CLI for supporting AdInsure development processes.
 
 `npm install -g @adinsure-ops/ops-cli`
 
+## HTTP proxy support
+
+HTTP requests use Node.js fetch with an undici proxy dispatcher.
+Set `HTTP_PROXY` and `HTTPS_PROXY` for your proxy, and `NO_PROXY` for hosts that
+must be reached directly. Lowercase equivalents take precedence; `ALL_PROXY`
+is used when the protocol-specific proxy variable is not set. No
+`NODE_USE_ENV_PROXY` flag is needed, including on Node.js 22.13.0.
+`HTTP_PROXY` applies only to HTTP, and `HTTPS_PROXY` only to HTTPS. `NO_PROXY`
+retains the existing matching rules: bare hosts match exactly; leading dots or
+wildcards match suffixes. HTTP requests use proxy forwarding; HTTPS uses CONNECT
+with certificate validation. Proxy credentials may use an empty password.
+
+Redirects to another origin drop authentication headers, including GitLab's
+`PRIVATE-TOKEN`, and a 307/308 redirect that would resend a request body to
+another origin is refused. Same-origin redirects retain credentials. Debug output includes
+the HTTP method and URL path, without headers, bodies or query strings.
+
 ## CLI development
 
-For development you will need **[Node.js](https://nodejs.org/en/)** (recommended 20 LTS, minimal 18.0.0) and **[Yarn](https://yarnpkg.com/en/)** installed.
+For live-service verification of the built package, see the [native fetch manual test guide](docs/testing/manual-testing.md).
+
+For development you will need **[Node.js](https://nodejs.org/en/)** (22.13.0+ on Node 22, or Node 24+) and **[Yarn](https://yarnpkg.com/en/)** installed.
 
 We recommend **[Visual Studio Code](https://code.visualstudio.com/)** IDE.
 
+Run `yarn test` for the main suite and `yarn test-unit` for the unit suite.
+`yarn test-with-coverage` runs the main suite with the detailed reporter and writes
+HTML, LCOV and Cobertura coverage reports to `coverage/`. Coverage uses c8 so that
+the TypeScript modules loaded through `ts-node/esm` are included.
+
+Mocha 12 currently uses `@types/mocha` 10.0.10, the latest published type definitions;
+there is no matching version 12 of the types package.
+
 To quick start development:
 
 - Clone this repository (`git clone https://git.adacta-fintech.com/ops/ops-cli.git`)
 - Open in VS Code
 - Run `yarn install`
+- Run `yarn build` to compile the CLI
 - For easier debugging, run `yarn link`
 
 You can run and debug commands directly from terminal by running `ops [command]` (if you `yarn link`-ed the package) or execute `.\bin\run [command]` (if you didn't link, e.g. `.\bin\run.cmd sql schema` for non-Windows environments and `.\bin\dev.cmd sql schema` for Windows environments). For debugging, you can follow oclif's documentation on how to turn on debug mode for a single command **[here](https://oclif.io/docs/debugging/)**.
 
+The compiler uses TypeScript 6 with NodeNext module resolution and full library type checking. Use `.js` extensions for relative imports in TypeScript source files. Run `yarn build`, `yarn eslint`, `yarn test`, and `yarn pack` to validate changes; the tests continue to use ts-node 10.
+
+TypeScript compatibility requires the scoped `**/path-scurry/lru-cache` resolution to 11.5.3. The 10.x cache declarations implement `Map` with incompatible iterator types and lack the new ESNext `Map` methods. Keep this resolution until the dependency chain provides compatible declarations; do not disable library checking.
+
+## Dependency management and SBOM (LJADIRD-66109)
+
+### SBOM and Dependency-Track
+
+The `sca:dbUp` job in [.build/.gitlab-ci-sca.yml](.build/.gitlab-ci-sca.yml) generates a
+CycloneDX SBOM with `dependency-track-cli` ([sbom.conf.yml](sbom.conf.yml)) and uploads it to
+the Dependency-Track project `ops-cli`. It runs on version tags, protected branches and the
+`SCA` pipeline schedule.
+
+The SBOM contains production dependencies only. The job installs with
+`yarn install --frozen-lockfile --production --ignore-scripts`, so devDependencies (build,
+test and lint tooling) are not in `node_modules` and are not reported. To reproduce locally:
+
+```sh
+yarn install --frozen-lockfile --production --ignore-scripts
+npx @cyclonedx/cyclonedx-npm --ignore-npm-errors --output-file ops-cli-BOM.json package.json
+```
+
+Record the outcome of every reviewed finding in Dependency-Track (analysis state and comment),
+for example *False positive* for withdrawn advisories or *Not affected* when the vulnerable code
+path is not used.
+
+### Renovate
+
+[renovate.json](renovate.json) defines the update policy. It is prepared but not yet run by any
+Renovate instance.
+
+- Patch and minor updates are grouped into one merge request per week (Monday morning).
+- Major updates are opened as separate merge requests.
+- Production `dependencies` stay pinned to exact versions; devDependencies keep caret ranges,
+  which are only raised when the new version is outside the range.
+- `yarn.lock` is refreshed weekly (lock file maintenance), which also updates transitive dependencies.
+- Security updates are opened immediately.
+- Node.js and `@types/node` majors, images from `adinsure.azurecr.io`, the `docs/` and
+  `.docs-engine/` packages and the `test/` fixtures are excluded.
+- To preview the merge requests without GitLab access, run
+  `LOG_LEVEL=debug npx renovate --platform=local` in the repository root (read-only).
+
+## Dependency maintenance (LJADIRD-66108)
+
+The upgrade retains TypeScript 6.0.3, typescript-eslint 8.72.1, Mocha 12.0.3,
+c8 12 and full library type checking. The chosen versions are:
+
+| Package | Version |
+| --- | --- |
+| `@oclif/core` | 5.1.11 |
+| `@oclif/plugin-help` | 7.0.6 |
+| `@oclif/plugin-not-found` | 4.0.7 |
+| `@oclif/plugin-warn-if-update-available` | 4.0.5 |
+| `@oclif/test` | 5.0.3 |
+| `oclif` | 6.0.15 |
+| `minimatch` | 11.0.4 |
+| `rimraf` | 6.1.4 |
+| `replace-in-file` | 9.0.0 |
+| `eslint` / `@eslint/js` | 10.14.0 / 10.0.1 |
+| `inquirer` | 14.2.5 |
+| `@azure/msal-node` | 7.2.0 |
+
+Node 22.13.0 replaces the previous 22.12.0 minimum: both Inquirer 14 and
+[ESLint 10](https://eslint.org/docs/latest/use/migrate-to-10.0.0) require it.
+Node 23 is excluded by the shared engine range. CI tests Node 22 and 24.
+This runtime requirement should be released as a major version; versioning and
+publication remain handled by the existing release-tag pipeline.
+
+Tests use `runCommand()` and `captureOutput()` following the
+[oclif test migration guide](https://github.com/oclif/test/blob/main/MIGRATION.md).
+The Mocha ESM root workaround is no longer needed. All 357 original main tests
+and 2 unit tests are retained. Additional regressions cover changelog confirmation
+(including cancellation and redirected output), replacement-file updates, and MSAL
+token acquisition and cache compatibility (367 main tests total). Prepare-content
+tests also exercise paths containing spaces. Mocha allows 20 seconds for source-mode
+command discovery on CI. `yarn test-with-coverage` still verifies executed TypeScript
+source lines. The command list, arguments, flags and top-level help are unchanged
+against the pre-upgrade master baseline (5215289). Top-level help also matches
+published 5.4.2 after normalizing the version. Two flag-description differences
+from that release (`log:add --force`, `npm:dependency-update --exclude`) already
+exist on master; this upgrade adds none.
+
+Inquirer uses its typed prompt API and modern `select` prompt in place of `list`;
+its bundled declarations replace `@types/inquirer`. Changelog generation uses
+Inquirer confirmation because oclif removed `ux.confirm`. The MSAL upgrade keeps
+the existing manually hosted authorization-code flow, which is unaffected by the
+[built-in loopback changes in v7](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/v7-migration.md).
+
+The Debian packaging job now runs for relevant merge requests as well as tags.
+After installation, `node test/smoke-package.mjs` checks help, version handling,
+a command's help from every topic, isolated config operations and a cached update
+warning without contacting external services. It also loads every CLI command
+implementation with the installed package's dependencies and bundled Node runtime;
+help alone only exercises manifest metadata. `ops version` is the release
+command and still requires a type; `ops --version` prints the CLI version.
+
+Validation on 2026-11-05 passed build, lint, all 367 main tests, both unit tests,
+and coverage integrity on Node 22.13.0 and 24.22.0, plus manifest generation on Node 24. Debian
+packages built for amd64 and arm64; installed-package smoke checks passed on
+arm64 and in the repository's amd64 Docker image as its non-root user. Real
+terminal input, selection and confirmation prompts were also checked.
+
+This is a maintenance upgrade, not a claim that the dependency tree is free of
+security findings. The direct minimatch dependency is upgraded; transitive glob
+and minimatch versions remain controlled by their upstream packages. Do not force
+incompatible transitive major versions to suppress audit findings.
+
 ## Upgrade guilde
 
 ### Upgrade to version 5.1.0
@@ -781,9 +916,12 @@ can start with or without the `/` character but using makes the syntax more read
 
 Example:
 {js:/transformations/templateRenderer.js}
+{js:/transformations/templateRenderer.mjs}
 ```
 
-JavaScript transformation is supported only for files, not directories.
+JavaScript transformation is supported only for files, not directories. Transformation modules can use
+`.js` or `.mjs` extensions. Async transformations finish before removal operations run; failures cause
+the command to exit with an error.
 
 Transformation module path should be relative to `.opsprepare` file but can start with `/` character
 for better readability. It can export multiple functions though only one can be used in single

package/bin/run.js

@@ -1,8 +1,4 @@
 #!/usr/bin/env node
-// eslint-disable-next-line
-import oclif from '@oclif/core';
+import { execute } from '@oclif/core';
 
-/* eslint-disable */
-oclif.run(process.argv.slice(2), import.meta.url)
-    .then(oclif.flush)
-    .catch(oclif.Errors.handle);
+await execute({ dir: import.meta.url });

package/lib/command.base.d.ts

@@ -1,7 +1,9 @@
 import { Command, Config } from '@oclif/core';
+import HttpClient from './lib/http.js';
 import SecurityContext from './security/context.js';
 export default abstract class CommandBase<T extends typeof Command> extends Command {
     protected readonly security: SecurityContext;
+    protected readonly http: HttpClient;
     private readonly childProcess;
     private readonly _yarnVersionRegex;
     constructor(argv: string[], config: Config);
@@ -22,5 +24,9 @@ export default abstract class CommandBase<T extends typeof Command> extends Comm
      * @returns {string[]} An array of files inside the directory with the specified filter
      */
     getFilesRecursive(dir: string, baseRelativePath: string, filter: RegExp): Promise<string[]>;
-    run(): Promise<any>;
+    protected catch(error: Error & {
+        exitCode?: number;
+    }): Promise<unknown>;
+    protected finally(error: Error | undefined): Promise<void>;
+    run(): Promise<unknown>;
 }

package/lib/command.base.jira.d.ts

@@ -1,10 +1,28 @@
-import JiraApi from 'jira-client';
 import CommandBase from './command.base.js';
+export interface JiraConnection {
+    baseUrl: string;
+    headers: Record<string, string>;
+}
+interface JiraIssue {
+    fields: {
+        labels: string[];
+    };
+}
+export type JiraLabelOperation = {
+    add: string;
+} | {
+    remove: string;
+};
 export default abstract class CommandBaseJira extends CommandBase<typeof CommandBaseJira> {
     static flags: {
-        username: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        password: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        hostname: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        username: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        password: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        hostname: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
-    jiraInit(urlString: string, username: string, password: string): Promise<JiraApi>;
+    protected jiraInit(urlString: string, username: string, password: string): JiraConnection;
+    protected getJiraIssue(jira: JiraConnection, issue: string): Promise<JiraIssue>;
+    protected updateJiraLabels(jira: JiraConnection, issue: string, labels: JiraLabelOperation[]): Promise<unknown>;
+    private jiraResponse;
+    private jiraErrorMessage;
 }
+export {};

package/lib/command.base.jira.js

@@ -1,23 +1,58 @@
 import { __awaiter } from "tslib";
 import { Flags } from '@oclif/core';
-import JiraApi from 'jira-client';
-import url from 'url';
 import CommandBase from './command.base.js';
+import { HttpError } from './lib/http.js';
 class CommandBaseJira extends CommandBase {
     jiraInit(urlString, username, password) {
+        const jiraUrl = new URL(urlString);
+        return {
+            // Preserve the existing hostname flag's treatment of ports and context paths.
+            baseUrl: `${jiraUrl.protocol}//${jiraUrl.hostname}/rest/api/2`,
+            headers: Object.assign({ Accept: 'application/json' }, (username && password ? { Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}` } : {})),
+        };
+    }
+    getJiraIssue(jira, issue) {
+        return this.jiraResponse(this.http.getJson(`${jira.baseUrl}/issue/${encodeURIComponent(issue)}`, {
+            headers: jira.headers,
+            params: { expand: '', fields: '*all', properties: '*all', fieldsByKeys: false },
+        }));
+    }
+    updateJiraLabels(jira, issue, labels) {
+        return this.jiraResponse(this.http.putJson(`${jira.baseUrl}/issue/${encodeURIComponent(issue)}`, {
+            update: { labels },
+        }, { headers: jira.headers }));
+    }
+    jiraResponse(request) {
         return __awaiter(this, void 0, void 0, function* () {
-            const jiraUrl = new url.URL(urlString);
-            const jira = new JiraApi({
-                protocol: jiraUrl.protocol,
-                host: jiraUrl.hostname,
-                username,
-                password,
-                apiVersion: '2',
-                strictSSL: true,
-            });
-            return jira;
+            try {
+                const { data } = yield request;
+                if (data && typeof data === 'object' && 'errorMessages' in data &&
+                    Array.isArray(data.errorMessages) && data.errorMessages.length > 0) {
+                    // jira-client serialized its application Error to an empty JSON object.
+                    throw new Error('{}');
+                }
+                return data;
+            }
+            catch (error) {
+                if (error instanceof HttpError) {
+                    // Oclif prints the name as well as the message. Keep the plain "Error:"
+                    // prefix without losing the shared HttpError instance/status/data.
+                    error.name = 'Error';
+                    error.message = this.jiraErrorMessage(error);
+                }
+                throw error;
+            }
         });
     }
+    jiraErrorMessage(error) {
+        if (error.status === 401) {
+            return 'Jira authentication failed (HTTP 401). Check the Jira username and password.';
+        }
+        // Keep Jira's JSON error details; never print HTML or other raw error pages.
+        if (error.data !== null && typeof error.data === 'object')
+            return JSON.stringify(error.data);
+        return `Jira request failed (HTTP ${error.status}).`;
+    }
 }
 CommandBaseJira.flags = {
     username: Flags.string({

package/lib/command.base.js

@@ -1,9 +1,9 @@
 import { __awaiter } from "tslib";
 import { Command, ux } from '@oclif/core';
-import axios from 'axios';
 import chalk from 'chalk';
 import fs from 'fs-extra';
-import path from 'path';
+import path from 'node:path';
+import HttpClient from './lib/http.js';
 import SecurityContext from './security/context.js';
 import ChildProcessCommand from './lib/command.js';
 /* eslint-disable-next-line @typescript-eslint/no-unused-vars */
@@ -12,7 +12,8 @@ export default class CommandBase extends Command {
         super(argv, config);
         this.childProcess = new ChildProcessCommand();
         this._yarnVersionRegex = /^\d+\.\d+\.\d+/;
-        this.security = new SecurityContext(this.config.configDir);
+        this.http = new HttpClient(message => this.debug(message));
+        this.security = new SecurityContext(this.config.configDir, this.http);
     }
     getGitRoot(startDir) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -102,13 +103,41 @@ export default class CommandBase extends Command {
             return files;
         });
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    catch(error) {
+        const _super = Object.create(null, {
+            catch: { get: () => super.catch }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            // Inquirer rejects with ExitPromptError when the user presses Ctrl+C at a prompt.
+            if ((error === null || error === void 0 ? void 0 : error.name) === 'ExitPromptError') {
+                if (ux.action.running) {
+                    ux.action.stop('aborted');
+                }
+                this.exit(130);
+            }
+            return _super.catch.call(this, error);
+        });
+    }
+    finally(error) {
+        const _super = Object.create(null, {
+            finally: { get: () => super.finally }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.http.close();
+            }
+            catch (_a) {
+                // Releasing idle connections must never replace the command's own result or error.
+                this.debug('HTTP client close failed');
+            }
+            finally {
+                yield _super.finally.call(this, error);
+            }
+        });
+    }
     run() {
         return __awaiter(this, void 0, void 0, function* () {
-            axios.interceptors.request.use(req => {
-                this.debug(`${chalk.bgCyan('DEBUG: ')} Request that was sent with your command:\n${JSON.stringify(req, null, 2)}`);
-                return req;
-            });
+            return undefined;
         });
     }
 }

package/lib/command.download.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import CommandBase from './command.base.js';
+import { HttpResponse } from './lib/http.js';
+export default abstract class DownloadCommand<T extends typeof Command> extends CommandBase<T> {
+    protected abstract readonly azureUrl: string;
+    protected abstract readonly packageName: string;
+    protected readonly extension: string;
+    private readonly gitlabUrl;
+    downloadFileFromAzure(version: string): Promise<HttpResponse<Buffer>>;
+    downloadFileFromGitLabRu(version: string): Promise<HttpResponse<Buffer>>;
+}

package/lib/command.download.js

@@ -0,0 +1,27 @@
+import { __awaiter } from "tslib";
+import CommandBase from './command.base.js';
+export default class DownloadCommand extends CommandBase {
+    constructor() {
+        super(...arguments);
+        this.extension = 'zip';
+        this.gitlabUrl = 'https://gitlabru.adacta-fintech.ru/api/v4/projects/2/packages/generic';
+    }
+    downloadFileFromAzure(version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.http.getBuffer(`${this.azureUrl}/${this.packageName}-${version}.${this.extension}`, {
+                headers: {
+                    Authorization: 'Bearer ' + (yield this.security.getToken()),
+                    'Content-Type': 'application/octet-stream',
+                },
+            });
+        });
+    }
+    downloadFileFromGitLabRu(version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fileName = `${this.packageName}-${version}.${this.extension}`;
+            return this.http.getBuffer(`${this.gitlabUrl}/${this.packageName}/${version}/${fileName}`, {
+                headers: { 'PRIVATE-TOKEN': this.security.getTokenRu() },
+            });
+        });
+    }
+}

package/lib/commands/config/get.d.ts

@@ -5,7 +5,7 @@ export default class ConfigGet extends CommandBase<typeof ConfigGet> {
     static usage: string;
     static examples: string[];
     static args: {
-        type: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        type: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<void>;
 }

package/lib/commands/config/list.js

@@ -12,7 +12,7 @@ class ConfigList extends CommandBase {
             const configPath = this.security.getConfigPath();
             const config = new OpsConfig(configPath);
             const allConfig = config.list();
-            this.log(chalk.green("config.json:"));
+            this.log(chalk.green('config.json:'));
             this.log(JSON.stringify(allConfig, null, 2));
         });
     }

package/lib/commands/config/set.d.ts

@@ -5,8 +5,8 @@ export default class ConfigSet extends CommandBase<typeof ConfigSet> {
     static usage: 'config:set <type> <value>';
     static examples: string[];
     static args: {
-        type: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
-        value: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        type: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        value: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<void>;
 }

package/lib/commands/config/set.js

@@ -2,8 +2,8 @@ import { __awaiter } from "tslib";
 import { Args } from '@oclif/core';
 import CommandBase from '../../command.base.js';
 import chalk from 'chalk';
-import fs from 'fs';
-import path from 'path';
+import fs from 'node:fs';
+import path from 'node:path';
 import OpsConfig from '../../lib/config.js';
 class ConfigSet extends CommandBase {
     run() {

package/lib/commands/config/unset.d.ts

@@ -5,7 +5,7 @@ export default class ConfigUnset extends CommandBase<typeof ConfigUnset> {
     static usage: string;
     static examples: string[];
     static args: {
-        type: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        type: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<void>;
 }

package/lib/commands/docker/update-image-version.d.ts

@@ -4,11 +4,39 @@ export default class DockerUpdateImageVersion extends CommandBase<typeof DockerU
     static usage: string;
     static examples: string[];
     static args: {
-        version: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        version: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
-        services: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[], import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        'file-path': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        services: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'file-path': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    /**
+     * Update the image tag of a single service. Aliases, alias keys and merge keys are resolved as YAML resolves them,
+     * and only the selected service changes, also when its image or mapping is shared with other nodes.
+     */
+    private updateImage;
+    /**
+     * Get the value of a key in a map as a node that belongs only to this map, so it can be changed without changing
+     * other nodes. An aliased or inherited value is replaced with a copy, and aliases of an anchored value get a copy.
+     */
+    private ownValue;
+    /**
+     * Find the pair of a key in a map. Keys may be aliases, and keys that are not in the map itself
+     * are looked up in its merge keys (<<), in the order YAML 1.1 merges them.
+     */
+    private findPair;
+    private keyValue;
+    private isMergeKey;
+    private resolveAlias;
+    /**
+     * Copy a node without its anchors, so the copy does not redefine them. Aliases in the node are replaced
+     * with copies of the nodes they resolve to where they are now, because they may resolve to another node
+     * where the copy is placed (an anchor can be redefined in between).
+     */
+    private copy;
+    /**
+     * Replace every alias of an anchored node with a copy of it, so changing the node does not change its aliases
+     */
+    private detachAliases;
 }