@icedq/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Torana Inc. (iceDQ)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @icedq/cli
+
+CLI for iceDQ rule and workflow promotion across environments.
+
+Wraps the iceDQ import/export REST APIs to handle authentication, async job polling, multipart bundle uploads, and import log parsing in a single command.
+
+## Install
+
+```bash
+npm install -g @icedq/cli
+```
+
+Requires Node.js 18 or newer.
+
+## Authenticate
+
+Set the following environment variables (or pass equivalent flags):
+
+| Variable | Description |
+|---|---|
+| `ICEDQ_URL` | iceDQ instance base URL, e.g. `https://app.icedq.com` |
+| `ICEDQ_KEYCLOAK_URL` | Keycloak token endpoint base, e.g. `https://auth.icedq.com/auth/realms/icedq` |
+| `ICEDQ_CLIENT_ID` | OAuth client ID (`client_credentials` grant) |
+| `ICEDQ_CLIENT_SECRET` | OAuth client secret |
+| `ICEDQ_ORG_ID` | iceDQ organization ID |
+| `ICEDQ_ACCOUNT_ID` | iceDQ account ID |
+| `ICEDQ_WORKSPACE_ID` | Source/target workspace ID |
+
+## Commands (v0.1)
+
+### `icedq export`
+
+Initiates an export, polls until complete, downloads the bundle.
+
+```bash
+icedq export --resource workflow --id wkfl-... --output-file ./finance.zip
+icedq export --resource folder   --id fldr-... --include-child --output-file ./finance.zip
+```
+
+### `icedq import`
+
+Submits a bundle, polls until complete, parses the log.
+
+```bash
+icedq import \
+  --bundle ./finance.zip \
+  --kind workflows \
+  --mapping-file ./mapping.json \
+  --strict \
+  --retain-log ./icedq-import.log
+```
+
+A hand-authored `mapping.json` is required in v0.1. Auto-mapping by name (`generate-mapping`) ships in v0.2.
+
+## GitHub Actions
+
+For CI/CD usage via GitHub Actions, see the **[Using the iceDQ GitHub Actions](docs/github-actions.md)** guide. It covers prerequisites (Keycloak `client_credentials` setup, GitHub secrets/environments), quick-start examples, a full Dev → QA → UAT → Prod promotion pipeline, mapping file authoring, self-hosted runners, troubleshooting, and FAQ.
+
+Companion repos:
+
+- [`icedq-tools/export-action`](https://github.com/icedq-tools/export-action)
+- [`icedq-tools/import-action`](https://github.com/icedq-tools/import-action)
+
+## Roadmap
+
+- v0.2 — `icedq generate-mapping`, `icedq jobs`, `icedq published`, `icedq validate`
+- v0.2 — companion GitHub Actions: `icedq/export-action`, `icedq/validate-action`
+
+The build specification is the source of truth for behavior.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@icedq/cli",
+  "version": "0.1.0",
+  "description": "CLI for iceDQ rule and workflow promotion across environments",
+  "type": "module",
+  "main": "src/bin/icedq.js",
+  "bin": {
+    "icedq": "./src/bin/icedq.js"
+  },
+  "scripts": {
+    "test": "node --test tests/unit/",
+    "start": "node src/bin/icedq.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "icedq",
+    "data-quality",
+    "ci-cd",
+    "promotion",
+    "github-action"
+  ],
+  "author": "iceDQ Integration Team",
+  "license": "MIT",
+  "homepage": "https://github.com/icedq-tools/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/icedq-tools/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/icedq-tools/cli/issues"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "form-data": "^4.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/bin/icedq.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { runExport } from '../commands/export.js';
+import { runImport } from '../commands/import.js';
+import { CliError } from '../core/errors.js';
+import { log } from '../core/logger.js';
+
+const program = new Command();
+
+program
+  .name('icedq')
+  .description('CLI for iceDQ rule and workflow promotion')
+  .version('0.1.0');
+
+function addGlobalOptions(cmd) {
+  cmd
+    .option('--icedq-url <url>', 'iceDQ instance base URL [env: ICEDQ_URL]')
+    .option('--keycloak-url <url>', 'Keycloak token endpoint base [env: ICEDQ_KEYCLOAK_URL]')
+    .option('--client-id <id>', 'OAuth client ID [env: ICEDQ_CLIENT_ID]')
+    .option('--client-secret <secret>', 'OAuth client secret [env: ICEDQ_CLIENT_SECRET]')
+    .option('--org-id <id>', '[env: ICEDQ_ORG_ID]')
+    .option('--account-id <id>', '[env: ICEDQ_ACCOUNT_ID]')
+    .option('--workspace-id <id>', '[env: ICEDQ_WORKSPACE_ID]')
+    .option('--verify-ssl <bool>', 'verify TLS (default true)')
+    .option('--timeout <seconds>', 'polling timeout in seconds', '1800')
+    .addOption(new Option('--output <format>', 'output format').choices(['text', 'json', 'markdown']).default('text'))
+    .option('-v, --verbose', 'verbose logging')
+    .option('-q, --quiet', 'suppress non-error logging');
+  return cmd;
+}
+
+addGlobalOptions(
+  program
+    .command('export')
+    .description('Export rules, workflows, or folders to a bundle')
+    .requiredOption('--resource <kind>', 'rule | workflow | folder')
+    .requiredOption('--id <uuid>', 'resource UUID')
+    .option('--include-child', 'recurse folder children (folder resource only)', false)
+    .requiredOption('--output-file <path>', 'where to write the bundle ZIP')
+).action(async (opts, cmd) => wrap(() => runExport(merge(cmd, opts))));
+
+addGlobalOptions(
+  program
+    .command('import')
+    .description('Import a bundle into the target workspace')
+    .requiredOption('--bundle <path>', 'path to the export ZIP')
+    .requiredOption('--kind <kind>', 'rules | workflows')
+    .requiredOption('--mapping-file <path>', 'mapping JSON (auto-generation arrives in v0.2)')
+    .option('--use-fqn', 'use FQN (name) resolution instead of UUIDs', false)
+    .option('--strict', 'exit non-zero on any skipped rule', false)
+    .option('--terminate-on-conflict', 'cancel any active import in the target workspace and retry', false)
+    .option('--retain-log <path>', 'write the full import log to this path')
+).action(async (opts, cmd) => wrap(() => runImport(merge(cmd, opts))));
+
+function merge(cmd, localOpts) {
+  return { ...cmd.parent.opts(), ...cmd.opts(), ...localOpts };
+}
+
+async function wrap(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    if (err instanceof CliError) {
+      log.error(err.message);
+      process.exit(err.exitCode || 1);
+    }
+    log.error(`Unexpected error: ${err.message}`, { stack: err.stack });
+    process.exit(1);
+  }
+}
+
+program.parseAsync(process.argv).catch((err) => {
+  log.error(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/src/commands/export.js

@@ -0,0 +1,100 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from '../core/config.js';
+import { KeycloakClientCredentialsAuth } from '../core/auth.js';
+import { IcedqApiClient } from '../core/client.js';
+import { pollTask } from '../core/poller.js';
+import { Reporter } from '../core/reporter.js';
+import { isSuccess, STATUS } from '../lib/status-enum.js';
+import { TaskFailedError, CliError } from '../core/errors.js';
+import { log, setLevel } from '../core/logger.js';
+
+const VALID_RESOURCES = new Set(['rule', 'workflow', 'folder']);
+
+function endpointForResource(resource) {
+  // Rules export uses /exports/rules; workflows + folders use /exports/workflows
+  return resource === 'rule' ? 'rules' : 'workflows';
+}
+
+export async function runExport(rawOpts) {
+  if (rawOpts.verbose) setLevel('debug');
+  if (rawOpts.quiet) setLevel('error');
+
+  const resource = rawOpts.resource;
+  if (!VALID_RESOURCES.has(resource)) {
+    throw new CliError(`--resource must be one of: rule, workflow, folder`);
+  }
+  if (!rawOpts.id) throw new CliError('--id is required');
+  if (!rawOpts.outputFile) throw new CliError('--output-file is required');
+
+  const cfg = loadConfig(rawOpts);
+  const auth = new KeycloakClientCredentialsAuth({
+    keycloakUrl: cfg.keycloakUrl,
+    clientId: cfg.clientId,
+    clientSecret: cfg.clientSecret,
+    verifySsl: cfg.verifySsl
+  });
+  const client = new IcedqApiClient({
+    baseUrl: cfg.icedqUrl,
+    orgId: cfg.orgId,
+    accountId: cfg.accountId,
+    workspaceId: cfg.workspaceId,
+    auth,
+    verifySsl: cfg.verifySsl
+  });
+
+  const kindEndpoint = endpointForResource(resource);
+  const body = [
+    {
+      id: rawOpts.id,
+      resource,
+      ...(rawOpts.includeChild ? { includeChild: 'true' } : {})
+    }
+  ];
+
+  log.info(`Submitting export`, { resource, id: rawOpts.id, endpoint: kindEndpoint });
+  const submitResp = await client.post(`/api/v1/exports/${kindEndpoint}`, body);
+  const taskId = submitResp.taskInstanceId;
+  if (!taskId) {
+    throw new CliError(`Export submit did not return a taskInstanceId: ${JSON.stringify(submitResp)}`);
+  }
+  process.stderr.write(`task-id: ${taskId}\n`);
+
+  log.info('Polling export task', { taskId, timeoutSec: cfg.timeoutSec });
+  const start = Date.now();
+  const { status, attempts, elapsedMs } = await pollTask(client, 'exports', taskId, {
+    timeoutSec: cfg.timeoutSec,
+    onTick: ({ status: s, attempt }) => log.debug('tick', { status: s, attempt })
+  });
+
+  let outputFile = rawOpts.outputFile;
+  let logTail;
+
+  if (isSuccess(status)) {
+    const buffer = await client.getBinary(`/api/v1/exports/${taskId}/download`);
+    outputFile = path.resolve(outputFile);
+    await writeFile(outputFile, buffer);
+    log.info('Export bundle written', { outputFile, bytes: buffer.length });
+  } else {
+    try {
+      logTail = await client.get(`/api/v1/exports/${taskId}/log`);
+    } catch (err) {
+      log.warn('Could not retrieve task log', { error: err.message });
+    }
+  }
+
+  const result = {
+    command: 'export',
+    taskId,
+    status,
+    attempts,
+    durationMs: elapsedMs,
+    outputFile: isSuccess(status) ? outputFile : undefined,
+    elapsedSinceSubmitMs: Date.now() - start
+  };
+  new Reporter(rawOpts.output || 'text').emit(result);
+
+  if (!isSuccess(status)) {
+    throw new TaskFailedError(taskId, 'export', status, logTail);
+  }
+}

package/src/commands/import.js

@@ -0,0 +1,175 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from '../core/config.js';
+import { KeycloakClientCredentialsAuth } from '../core/auth.js';
+import { IcedqApiClient } from '../core/client.js';
+import { pollTask } from '../core/poller.js';
+import { Reporter } from '../core/reporter.js';
+import { parseImportLog } from '../lib/log-parser.js';
+import { isSuccess } from '../lib/status-enum.js';
+import { ApiError, BundleError, CliError, TaskFailedError } from '../core/errors.js';
+import { log, setLevel } from '../core/logger.js';
+
+const VALID_KINDS = new Set(['rules', 'workflows']);
+
+export async function runImport(rawOpts) {
+  if (rawOpts.verbose) setLevel('debug');
+  if (rawOpts.quiet) setLevel('error');
+
+  if (!rawOpts.bundle) throw new CliError('--bundle is required');
+  if (!rawOpts.kind || !VALID_KINDS.has(rawOpts.kind)) {
+    throw new CliError(`--kind must be one of: rules, workflows`);
+  }
+  if (!rawOpts.mappingFile) {
+    throw new CliError(
+      '--mapping-file is required in v0.1. Auto-mapping (`generate-mapping`) ships in v0.2.'
+    );
+  }
+
+  const cfg = loadConfig(rawOpts);
+  const auth = new KeycloakClientCredentialsAuth({
+    keycloakUrl: cfg.keycloakUrl,
+    clientId: cfg.clientId,
+    clientSecret: cfg.clientSecret,
+    verifySsl: cfg.verifySsl
+  });
+  const client = new IcedqApiClient({
+    baseUrl: cfg.icedqUrl,
+    orgId: cfg.orgId,
+    accountId: cfg.accountId,
+    workspaceId: cfg.workspaceId,
+    auth,
+    verifySsl: cfg.verifySsl
+  });
+
+  const bundlePath = path.resolve(rawOpts.bundle);
+  const mappingPath = path.resolve(rawOpts.mappingFile);
+
+  let bundleBuffer;
+  try {
+    bundleBuffer = await readFile(bundlePath);
+  } catch (err) {
+    throw new BundleError(`could not read bundle at ${bundlePath}: ${err.message}`);
+  }
+
+  let mappingDoc;
+  try {
+    const text = await readFile(mappingPath, 'utf8');
+    mappingDoc = JSON.parse(text);
+  } catch (err) {
+    throw new CliError(`could not parse --mapping-file at ${mappingPath}: ${err.message}`);
+  }
+
+  if (rawOpts.useFqn !== undefined) {
+    mappingDoc.useFqn = !!rawOpts.useFqn;
+  }
+  if (mappingDoc.useFqn === undefined) mappingDoc.useFqn = false;
+
+  const submitParts = {
+    file: {
+      buffer: bundleBuffer,
+      filename: path.basename(bundlePath),
+      contentType: 'application/zip'
+    },
+    mapping: { json: mappingDoc }
+  };
+
+  const importPath = `/api/v1/imports/${rawOpts.kind}`;
+  log.info('Submitting import', { kind: rawOpts.kind, bundle: bundlePath, mapping: mappingPath });
+
+  let submitResp;
+  try {
+    submitResp = await client.postMultipart(importPath, submitParts);
+  } catch (err) {
+    if (err instanceof ApiError && err.isConstraintViolation()) {
+      const result = {
+        command: 'import',
+        status: 'ConstraintViolation',
+        hardErrors: err.messages.map(
+          (m) => `${m.fieldName ? m.fieldName + ': ' : ''}${m.violation || m.message || ''}`
+        )
+      };
+      new Reporter(rawOpts.output || 'text').emit(result);
+      throw err;
+    }
+    if (err instanceof ApiError && err.status === 409 && rawOpts.terminateOnConflict) {
+      log.warn('Active import job conflicts; locating and terminating');
+      await terminateActiveImport(client);
+      submitResp = await client.postMultipart(importPath, submitParts);
+    } else {
+      throw err;
+    }
+  }
+
+  const taskId = submitResp.taskInstanceId;
+  if (!taskId) throw new CliError(`Import submit did not return taskInstanceId: ${JSON.stringify(submitResp)}`);
+  process.stderr.write(`task-id: ${taskId}\n`);
+
+  const start = Date.now();
+  const { status, elapsedMs, attempts } = await pollTask(client, 'imports', taskId, {
+    timeoutSec: cfg.timeoutSec,
+    onTick: ({ status: s, attempt }) => log.debug('tick', { status: s, attempt })
+  });
+
+  let logText = '';
+  try {
+    logText = await client.get(`/api/v1/imports/${taskId}/log`);
+    if (typeof logText !== 'string') logText = JSON.stringify(logText);
+  } catch (err) {
+    log.warn('Could not retrieve import log', { error: err.message });
+  }
+
+  if (rawOpts.retainLog && logText) {
+    const logPath = path.resolve(rawOpts.retainLog);
+    try {
+      await writeFile(logPath, logText, 'utf8');
+      log.info('Import log retained', { logPath });
+    } catch (err) {
+      log.warn('Could not write retained log', { logPath, error: err.message });
+    }
+  }
+
+  const parsed = parseImportLog(logText);
+  const result = {
+    command: 'import',
+    taskId,
+    status,
+    attempts,
+    durationMs: elapsedMs,
+    skippedCount: parsed.skippedCount,
+    skippedRules: parsed.skippedRules,
+    hardErrors: parsed.hardErrors,
+    elapsedSinceSubmitMs: Date.now() - start
+  };
+  new Reporter(rawOpts.output || 'text').emit(result);
+
+  if (!isSuccess(status)) {
+    throw new TaskFailedError(taskId, 'import', status);
+  }
+  if (rawOpts.strict && parsed.skippedCount > 0) {
+    const e = new CliError(
+      `--strict: import completed but ${parsed.skippedCount} rule(s) skipped. See log for details.`
+    );
+    e.exitCode = 1;
+    throw e;
+  }
+}
+
+async function terminateActiveImport(client) {
+  const search = await client.post('/api/v1/taskruns/search', {
+    filter: [
+      { attribute: 'type', operator: 'In', value: 'import-rules' },
+      { attribute: 'type', operator: 'In', value: 'import-workflows' }
+    ]
+  });
+  const active = (search?.items || search?.taskRuns || []).find((r) =>
+    ['Submitted', 'Running'].includes(r.taskStatus || r.status)
+  );
+  if (!active) {
+    log.warn('No active import found to terminate');
+    return;
+  }
+  const id = active.id || active.taskInstanceId;
+  log.info('Terminating active import', { taskId: id });
+  await client.post(`/api/v1/imports/${id}:terminate`, {});
+}

package/src/core/auth.js

@@ -0,0 +1,101 @@
+import https from 'node:https';
+import http from 'node:http';
+import { URL } from 'node:url';
+import { AuthError } from './errors.js';
+import { log } from './logger.js';
+
+const REFRESH_BUFFER_MS = 30 * 1000;
+
+export class KeycloakClientCredentialsAuth {
+  constructor({ keycloakUrl, clientId, clientSecret, verifySsl = true }) {
+    if (!keycloakUrl || !clientId || !clientSecret) {
+      throw new AuthError('keycloakUrl, clientId, and clientSecret are required');
+    }
+    this.keycloakUrl = keycloakUrl.replace(/\/+$/, '');
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.verifySsl = verifySsl;
+    this._token = null;
+    this._expiresAt = 0;
+    this._inFlight = null;
+  }
+
+  async getToken() {
+    if (this._token && Date.now() < this._expiresAt - REFRESH_BUFFER_MS) {
+      return this._token;
+    }
+    if (!this._inFlight) {
+      this._inFlight = this._fetchToken().finally(() => {
+        this._inFlight = null;
+      });
+    }
+    return this._inFlight;
+  }
+
+  async forceRefresh() {
+    this._token = null;
+    this._expiresAt = 0;
+    return this.getToken();
+  }
+
+  async _fetchToken() {
+    const tokenUrl = `${this.keycloakUrl}/protocol/openid-connect/token`;
+    const body = new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    }).toString();
+
+    log.debug('Requesting Keycloak token', { url: tokenUrl, clientId: this.clientId });
+
+    const response = await this._post(tokenUrl, body);
+
+    if (!response.access_token) {
+      throw new AuthError('Token response missing access_token');
+    }
+
+    this._token = response.access_token;
+    const ttlMs = (response.expires_in ?? 300) * 1000;
+    this._expiresAt = Date.now() + ttlMs;
+
+    log.info('Keycloak token acquired', { expiresInSec: response.expires_in ?? 300 });
+    return this._token;
+  }
+
+  _post(urlString, body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(urlString);
+      const isHttps = url.protocol === 'https:';
+      const lib = isHttps ? https : http;
+      const opts = {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(body),
+          Accept: 'application/json'
+        }
+      };
+      if (isHttps && !this.verifySsl) opts.rejectUnauthorized = false;
+
+      const req = lib.request(url, opts, (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new AuthError(`HTTP ${res.statusCode} from Keycloak: ${text}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(text));
+          } catch (err) {
+            reject(new AuthError(`Invalid JSON from Keycloak: ${err.message}`));
+          }
+        });
+      });
+      req.on('error', (err) => reject(new AuthError(err.message, { cause: err })));
+      req.write(body);
+      req.end();
+    });
+  }
+}

package/src/core/client.js

@@ -0,0 +1,182 @@
+import https from 'node:https';
+import http from 'node:http';
+import { URL } from 'node:url';
+import FormData from 'form-data';
+import { ApiError } from './errors.js';
+import { log } from './logger.js';
+
+const STATUS_RETRY_5XX = 3;
+const STATUS_RETRY_DELAY_MS = 5000;
+
+const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+
+export class IcedqApiClient {
+  constructor({ baseUrl, orgId, accountId, workspaceId, auth, verifySsl = true }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.orgId = orgId;
+    this.accountId = accountId;
+    this.workspaceId = workspaceId;
+    this.auth = auth;
+    this.verifySsl = verifySsl;
+  }
+
+  _buildHeaders(extra = {}, { includeWorkspace = true } = {}) {
+    const headers = {
+      Accept: 'application/json',
+      'Org-Id': this.orgId,
+      'Account-Id': this.accountId,
+      ...extra
+    };
+    if (includeWorkspace && this.workspaceId) {
+      headers['Workspace-Id'] = this.workspaceId;
+    }
+    return headers;
+  }
+
+  async get(path, opts = {}) {
+    return this._request('GET', path, opts);
+  }
+
+  async post(path, body, opts = {}) {
+    return this._request('POST', path, { ...opts, jsonBody: body });
+  }
+
+  async postMultipart(path, parts, opts = {}) {
+    const form = new FormData();
+    for (const [name, value] of Object.entries(parts)) {
+      if (value && typeof value === 'object' && value.buffer && value.filename) {
+        form.append(name, value.buffer, {
+          filename: value.filename,
+          contentType: value.contentType || 'application/octet-stream'
+        });
+      } else if (value && typeof value === 'object' && value.json !== undefined) {
+        form.append(name, JSON.stringify(value.json), { contentType: 'application/json' });
+      } else {
+        form.append(name, value);
+      }
+    }
+    return this._request('POST', path, { ...opts, multipart: form });
+  }
+
+  async getBinary(path, opts = {}) {
+    return this._request('GET', path, { ...opts, expectBinary: true });
+  }
+
+  async _request(method, path, opts = {}) {
+    const includeWorkspace = opts.includeWorkspace !== false;
+    let attempt = 0;
+    let last401 = false;
+
+    while (true) {
+      attempt++;
+      const token = await this.auth.getToken();
+      const headers = this._buildHeaders(
+        {
+          Authorization: `Bearer ${token}`,
+          ...(opts.headers || {})
+        },
+        { includeWorkspace }
+      );
+
+      let bodyBuffer;
+      if (opts.multipart) {
+        Object.assign(headers, opts.multipart.getHeaders());
+        bodyBuffer = opts.multipart.getBuffer();
+      } else if (opts.jsonBody !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        bodyBuffer = Buffer.from(JSON.stringify(opts.jsonBody));
+      }
+
+      const url = path.startsWith('http')
+        ? path
+        : `${this.baseUrl}${path.startsWith('/') ? '' : '/'}${path}`;
+
+      log.debug('iceDQ request', { method, url, attempt });
+
+      let response;
+      try {
+        response = await this._doRequest(method, url, headers, bodyBuffer, !!opts.expectBinary);
+      } catch (err) {
+        throw new ApiError(`Network error calling ${url}: ${err.message}`, { endpoint: path });
+      }
+
+      if (response.status === 401 && !last401) {
+        log.warn('iceDQ 401 — refreshing token and retrying once');
+        last401 = true;
+        await this.auth.forceRefresh();
+        continue;
+      }
+
+      if (response.status >= 500 && opts.retryOn5xx && attempt <= STATUS_RETRY_5XX) {
+        log.warn(`iceDQ ${response.status} — retrying after ${STATUS_RETRY_DELAY_MS}ms`, { attempt });
+        await sleep(STATUS_RETRY_DELAY_MS);
+        continue;
+      }
+
+      if (response.status < 200 || response.status >= 300) {
+        const parsed = parseErrorBody(response.body);
+        throw new ApiError(`HTTP ${response.status} from ${path}: ${parsed.summary}`, {
+          status: response.status,
+          code: parsed.code,
+          messages: parsed.messages,
+          body: response.body,
+          endpoint: path
+        });
+      }
+
+      if (opts.expectBinary) return response.buffer;
+      if (!response.body) return {};
+      try {
+        return JSON.parse(response.body);
+      } catch {
+        return response.body;
+      }
+    }
+  }
+
+  _doRequest(method, urlString, headers, bodyBuffer, expectBinary) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(urlString);
+      const isHttps = url.protocol === 'https:';
+      const lib = isHttps ? https : http;
+      const reqOpts = { method, headers };
+      if (isHttps && !this.verifySsl) reqOpts.rejectUnauthorized = false;
+
+      const req = lib.request(url, reqOpts, (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => {
+          if (expectBinary) {
+            resolve({ status: res.statusCode, buffer: Buffer.concat(chunks) });
+          } else {
+            resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') });
+          }
+        });
+      });
+      req.on('error', reject);
+      if (bodyBuffer) req.write(bodyBuffer);
+      req.end();
+    });
+  }
+}
+
+function parseErrorBody(body) {
+  if (!body) return { summary: '(empty body)', code: undefined, messages: [] };
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === 'object') {
+      const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+      const summary =
+        messages
+          .map((m) => `${m.fieldName ? m.fieldName + ': ' : ''}${m.violation || m.message || ''}`)
+          .filter(Boolean)
+          .join('; ') || parsed.message || JSON.stringify(parsed);
+      return { summary, code: parsed.code, messages };
+    }
+  } catch {
+    // not JSON, fall through
+  }
+  return { summary: body.slice(0, 200), code: undefined, messages: [] };
+}
+
+export const _internal = { parseErrorBody };

package/src/core/config.js

@@ -0,0 +1,68 @@
+import { ConfigError } from './errors.js';
+
+const FIELD_TO_ENV = {
+  icedqUrl: 'ICEDQ_URL',
+  keycloakUrl: 'ICEDQ_KEYCLOAK_URL',
+  clientId: 'ICEDQ_CLIENT_ID',
+  clientSecret: 'ICEDQ_CLIENT_SECRET',
+  orgId: 'ICEDQ_ORG_ID',
+  accountId: 'ICEDQ_ACCOUNT_ID',
+  workspaceId: 'ICEDQ_WORKSPACE_ID',
+  verifySsl: 'ICEDQ_VERIFY_SSL',
+  timeout: 'ICEDQ_TIMEOUT'
+};
+
+const DEFAULT_REQUIRED = ['icedqUrl', 'keycloakUrl', 'clientId', 'clientSecret', 'orgId', 'accountId'];
+
+function pick(opts, key, env) {
+  const flag = opts[key];
+  if (flag !== undefined && flag !== null && flag !== '') return flag;
+  const envName = FIELD_TO_ENV[key];
+  const envVal = env[envName];
+  if (envVal !== undefined && envVal !== '') return envVal;
+  return undefined;
+}
+
+function toBool(v, fallback) {
+  if (v === undefined) return fallback;
+  if (typeof v === 'boolean') return v;
+  const s = String(v).toLowerCase().trim();
+  if (['true', '1', 'yes', 'y'].includes(s)) return true;
+  if (['false', '0', 'no', 'n'].includes(s)) return false;
+  return fallback;
+}
+
+function toInt(v, fallback) {
+  if (v === undefined || v === null || v === '') return fallback;
+  const n = Number.parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function trimTrailingSlash(url) {
+  return typeof url === 'string' ? url.replace(/\/+$/, '') : url;
+}
+
+export function loadConfig(opts = {}, env = process.env, { requireWorkspace = true } = {}) {
+  const required = requireWorkspace ? [...DEFAULT_REQUIRED, 'workspaceId'] : DEFAULT_REQUIRED;
+
+  const cfg = {
+    icedqUrl: trimTrailingSlash(pick(opts, 'icedqUrl', env)),
+    keycloakUrl: trimTrailingSlash(pick(opts, 'keycloakUrl', env)),
+    clientId: pick(opts, 'clientId', env),
+    clientSecret: pick(opts, 'clientSecret', env),
+    orgId: pick(opts, 'orgId', env),
+    accountId: pick(opts, 'accountId', env),
+    workspaceId: pick(opts, 'workspaceId', env),
+    verifySsl: toBool(pick(opts, 'verifySsl', env), true),
+    timeoutSec: toInt(pick(opts, 'timeout', env), 1800)
+  };
+
+  const missing = required.filter((k) => !cfg[k]);
+  if (missing.length > 0) {
+    throw new ConfigError(missing.map((k) => FIELD_TO_ENV[k]));
+  }
+
+  return Object.freeze(cfg);
+}
+
+export const _internal = { FIELD_TO_ENV, DEFAULT_REQUIRED };

package/src/core/errors.js

@@ -0,0 +1,62 @@
+export class CliError extends Error {
+  constructor(message, { exitCode = 1, cause } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.exitCode = exitCode;
+    if (cause) this.cause = cause;
+  }
+}
+
+export class ConfigError extends CliError {
+  constructor(missing) {
+    const list = Array.isArray(missing) ? missing : [missing];
+    super(`Missing required configuration: ${list.join(', ')}`, { exitCode: 2 });
+    this.missing = list;
+  }
+}
+
+export class AuthError extends CliError {
+  constructor(message, { cause } = {}) {
+    super(`Authentication failed: ${message}`, { exitCode: 2, cause });
+  }
+}
+
+export class ApiError extends CliError {
+  constructor(message, { status, code, messages, body, endpoint } = {}) {
+    super(message, { exitCode: 2 });
+    this.status = status;
+    this.code = code;
+    this.messages = messages;
+    this.body = body;
+    this.endpoint = endpoint;
+  }
+
+  isConstraintViolation() {
+    return this.code === 'ConstraintViolation';
+  }
+}
+
+export class PollTimeoutError extends CliError {
+  constructor(taskId, kind, elapsedMs) {
+    super(`Timed out waiting for ${kind} task ${taskId} after ${elapsedMs}ms`, { exitCode: 3 });
+    this.taskId = taskId;
+    this.kind = kind;
+    this.elapsedMs = elapsedMs;
+  }
+}
+
+export class TaskFailedError extends CliError {
+  constructor(taskId, kind, status, logTail) {
+    super(`${kind} task ${taskId} ended in status ${status}`, { exitCode: 1 });
+    this.taskId = taskId;
+    this.kind = kind;
+    this.status = status;
+    this.logTail = logTail;
+  }
+}
+
+export class BundleError extends CliError {
+  constructor(message) {
+    super(`Bundle error: ${message}`, { exitCode: 2 });
+  }
+}

package/src/core/logger.js

@@ -0,0 +1,58 @@
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+
+let level = LEVELS.info;
+
+export function setLevel(name) {
+  if (Object.prototype.hasOwnProperty.call(LEVELS, name)) {
+    level = LEVELS[name];
+  }
+}
+
+const TOKEN_PATTERNS = [
+  /Bearer\s+[A-Za-z0-9._\-+/=]+/g,
+  /(access_token|refresh_token|client_secret)["':\s=]+["']?[A-Za-z0-9._\-+/=]+["']?/gi
+];
+
+function maskTokens(value) {
+  if (typeof value === 'string') {
+    let out = value;
+    for (const pattern of TOKEN_PATTERNS) {
+      out = out.replace(pattern, (m) => {
+        const head = m.slice(0, m.indexOf(' ') > 0 ? m.indexOf(' ') + 1 : 12);
+        return `${head}***`;
+      });
+    }
+    return out;
+  }
+  if (value && typeof value === 'object') {
+    const clone = Array.isArray(value) ? [] : {};
+    for (const [k, v] of Object.entries(value)) {
+      if (/(authorization|token|secret|password)/i.test(k)) {
+        clone[k] = '***';
+      } else {
+        clone[k] = maskTokens(v);
+      }
+    }
+    return clone;
+  }
+  return value;
+}
+
+function emit(name, lvl, msg, ctx) {
+  if (lvl > level) return;
+  const stamp = new Date().toISOString();
+  const safeCtx = ctx ? maskTokens(ctx) : undefined;
+  const line = safeCtx
+    ? `[${stamp}] ${name.toUpperCase()} ${maskTokens(msg)} ${JSON.stringify(safeCtx)}`
+    : `[${stamp}] ${name.toUpperCase()} ${maskTokens(msg)}`;
+  process.stderr.write(line + '\n');
+}
+
+export const log = {
+  error: (msg, ctx) => emit('error', LEVELS.error, msg, ctx),
+  warn:  (msg, ctx) => emit('warn',  LEVELS.warn,  msg, ctx),
+  info:  (msg, ctx) => emit('info',  LEVELS.info,  msg, ctx),
+  debug: (msg, ctx) => emit('debug', LEVELS.debug, msg, ctx)
+};
+
+export const _internal = { maskTokens };

package/src/core/poller.js

@@ -0,0 +1,60 @@
+import { isTerminal } from '../lib/status-enum.js';
+import { PollTimeoutError } from './errors.js';
+import { log } from './logger.js';
+
+const INITIAL_DELAY_MS = 2000;
+const MAX_DELAY_MS = 30000;
+const BACKOFF = 2;
+
+const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+
+export async function pollTask(client, kind, taskId, opts = {}) {
+  if (kind !== 'exports' && kind !== 'imports') {
+    throw new Error(`pollTask: kind must be 'exports' or 'imports', got '${kind}'`);
+  }
+
+  const timeoutMs = (opts.timeoutSec ?? 1800) * 1000;
+  const onTick = opts.onTick || (() => {});
+  const sleeper = opts.sleep || sleep;
+  const now = opts.now || (() => Date.now());
+
+  const start = now();
+  let delay = opts.initialDelayMs ?? INITIAL_DELAY_MS;
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    const elapsedMs = now() - start;
+    if (elapsedMs >= timeoutMs) {
+      throw new PollTimeoutError(taskId, kind, elapsedMs);
+    }
+
+    const remaining = timeoutMs - elapsedMs;
+    const waitMs = Math.min(delay, remaining);
+    await sleeper(waitMs);
+
+    let response;
+    try {
+      response = await client.get(`/api/v1/${kind}/${taskId}/status`, { retryOn5xx: true });
+    } catch (err) {
+      log.warn('Status poll failed', { taskId, attempt, error: err.message });
+      throw err;
+    }
+
+    const status = extractStatus(response);
+    onTick({ status, attempt, elapsedMs: now() - start, response });
+
+    if (isTerminal(status)) {
+      return { status, response, attempts: attempt, elapsedMs: now() - start };
+    }
+
+    delay = Math.min(delay * BACKOFF, MAX_DELAY_MS);
+  }
+}
+
+function extractStatus(response) {
+  if (!response || typeof response !== 'object') return undefined;
+  return response.taskStatus || response.status || response.state;
+}
+
+export const _internal = { extractStatus, INITIAL_DELAY_MS, MAX_DELAY_MS, BACKOFF };

package/src/core/reporter.js

@@ -0,0 +1,64 @@
+export class Reporter {
+  constructor(format = 'text') {
+    this.format = format;
+  }
+
+  emit(result) {
+    switch (this.format) {
+      case 'json':
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      case 'markdown':
+        process.stdout.write(toMarkdown(result) + '\n');
+        return;
+      case 'text':
+      default:
+        process.stdout.write(toText(result) + '\n');
+    }
+  }
+}
+
+function toText(r) {
+  const lines = [];
+  lines.push(`Command:   ${r.command}`);
+  if (r.taskId) lines.push(`Task ID:   ${r.taskId}`);
+  lines.push(`Status:    ${r.status}`);
+  if (r.durationMs !== undefined) lines.push(`Duration:  ${(r.durationMs / 1000).toFixed(1)}s`);
+  if (r.outputFile) lines.push(`Output:    ${r.outputFile}`);
+  if (r.skippedCount !== undefined) lines.push(`Skipped:   ${r.skippedCount}`);
+
+  if (r.skippedRules?.length) {
+    lines.push('');
+    lines.push('Skipped rules:');
+    for (const s of r.skippedRules) lines.push(`  - ${s.name}: ${s.reason}`);
+  }
+  if (r.hardErrors?.length) {
+    lines.push('');
+    lines.push('Errors:');
+    for (const e of r.hardErrors) lines.push(`  - ${e}`);
+  }
+  return lines.join('\n');
+}
+
+function toMarkdown(r) {
+  const lines = [];
+  lines.push(`## iceDQ ${r.command}`);
+  lines.push('');
+  lines.push(`- **Status:** ${r.status}`);
+  if (r.taskId) lines.push(`- **Task ID:** \`${r.taskId}\``);
+  if (r.durationMs !== undefined) lines.push(`- **Duration:** ${(r.durationMs / 1000).toFixed(1)}s`);
+  if (r.outputFile) lines.push(`- **Output:** \`${r.outputFile}\``);
+  if (r.skippedCount !== undefined) lines.push(`- **Skipped:** ${r.skippedCount}`);
+
+  if (r.skippedRules?.length) {
+    lines.push('');
+    lines.push('### Skipped rules');
+    for (const s of r.skippedRules) lines.push(`- \`${s.name}\` — ${s.reason}`);
+  }
+  if (r.hardErrors?.length) {
+    lines.push('');
+    lines.push('### Errors');
+    for (const e of r.hardErrors) lines.push(`- ${e}`);
+  }
+  return lines.join('\n');
+}

package/src/lib/log-parser.js

@@ -0,0 +1,55 @@
+const SKIP_PATTERNS = [
+  /(?:Skipped|Skipping)\s+(?:rule|workflow)\s+["']?([^"'\s:]+)["']?\s*[:\-]?\s*(.+?)$/i,
+  /Rule\s+["']?([^"'\s]+)["']?\s+(?:was\s+)?skipped\s*[:\-]?\s*(.+?)$/i
+];
+
+const ERROR_PATTERNS = [
+  /^\s*(?:ERROR|FATAL)\b\s*[:\-]?\s*(.+)$/i,
+  /^\s*Error\s*[:\-]\s*(.+)$/
+];
+
+export function parseImportLog(text) {
+  if (!text || typeof text !== 'string') {
+    return { skippedCount: 0, skippedRules: [], hardErrors: [] };
+  }
+
+  const skippedRules = [];
+  const hardErrors = [];
+  const seenSkips = new Set();
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    let matched = false;
+    for (const re of SKIP_PATTERNS) {
+      const m = line.match(re);
+      if (m) {
+        const name = m[1].trim();
+        const reason = (m[2] || 'skipped').trim();
+        const key = `${name}::${reason}`;
+        if (!seenSkips.has(key)) {
+          seenSkips.add(key);
+          skippedRules.push({ name, reason });
+        }
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
+
+    for (const re of ERROR_PATTERNS) {
+      const m = line.match(re);
+      if (m) {
+        hardErrors.push(m[1].trim());
+        break;
+      }
+    }
+  }
+
+  return {
+    skippedCount: skippedRules.length,
+    skippedRules,
+    hardErrors
+  };
+}

package/src/lib/status-enum.js

@@ -0,0 +1,17 @@
+export const STATUS = {
+  SUBMITTED: 'Submitted',
+  RUNNING: 'Running',
+  COMPLETED: 'Completed',
+  TERMINATED: 'Terminated',
+  ERROR: 'Error'
+};
+
+export const TERMINAL_STATES = new Set([STATUS.COMPLETED, STATUS.TERMINATED, STATUS.ERROR]);
+
+export function isTerminal(status) {
+  return TERMINAL_STATES.has(status);
+}
+
+export function isSuccess(status) {
+  return status === STATUS.COMPLETED;
+}