@icedq/cli 0.1.1 → 0.2.0

package/LICENSE

@@ -1,21 +1,201 @@
-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.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Torana Inc. (iceDQ)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,16 @@
+iceDQ CLI (@icedq/cli)
+Copyright 2026 Torana Inc. (iceDQ)
+
+This product includes software developed by Torana Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icedq/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI for iceDQ rule and workflow promotion across environments",
   "type": "module",
   "main": "src/bin/icedq.js",
@@ -8,8 +8,9 @@
     "icedq": "./src/bin/icedq.js"
   },
   "scripts": {
-    "test": "node --test tests/unit/*.test.js",
-    "start": "node src/bin/icedq.js"
+    "test": "node --test",
+    "start": "node src/bin/icedq.js",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -22,7 +23,10 @@
     "github-action"
   ],
   "author": "iceDQ Integration Team",
-  "license": "MIT",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "homepage": "https://github.com/icedq-tools/cli#readme",
   "repository": {
     "type": "git",
@@ -38,6 +42,7 @@
   "files": [
     "src/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ]
 }

package/src/bin/icedq.js

@@ -1,75 +1,84 @@
-#!/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);
-});
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { runExport } from '../commands/export.js';
+import { runImport } from '../commands/import.js';
+import { runGenerateMapping } from '../commands/generate-mapping.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('generate-mapping')
+    .description('Auto-generate a mapping file from an export bundle')
+    .requiredOption('--bundle <path>', 'path to the export ZIP')
+    .requiredOption('--output-file <path>', 'where to write the mapping JSON')
+).action(async (opts, cmd) => wrap(() => runGenerateMapping(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/generate-mapping.js

@@ -0,0 +1,217 @@
+import { readFile, writeFile, mkdir } 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 { Reporter } from '../core/reporter.js';
+import { ApiError, CliError } from '../core/errors.js';
+import { log, setLevel } from '../core/logger.js';
+
+const PAGE_SIZE = 1000;
+
+export async function runGenerateMapping(rawOpts) {
+  if (rawOpts.verbose) setLevel('debug');
+  if (rawOpts.quiet) setLevel('error');
+
+  if (!rawOpts.bundle) throw new CliError('--bundle 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 bundlePath = path.resolve(rawOpts.bundle);
+  let bundleBuffer;
+  try {
+    bundleBuffer = await readFile(bundlePath);
+  } catch (err) {
+    throw new CliError(`could not read bundle at ${bundlePath}: ${err.message}`);
+  }
+
+  // Step 1: get expected mappings from bundle
+  log.info('Uploading bundle to get expected mappings');
+  const expected = await client.postMultipart('/api/v1/internal/imports/mapping', {
+    file: {
+      buffer: bundleBuffer,
+      filename: path.basename(bundlePath),
+      contentType: 'application/zip'
+    }
+  });
+
+  const srcConnections = expected.connections || [];
+  const srcParameters = expected.parameters || [];
+  const srcCustomFields = expected.customFields || [];
+
+  log.info('Expected mappings', {
+    connections: srcConnections.length,
+    parameters: srcParameters.length,
+    customFields: srcCustomFields.length
+  });
+
+  // Step 2: resolve connections from target environment
+  const connections = await resolveConnections(client, srcConnections);
+
+  // Step 3: resolve parameters from target environment
+  const parameters = await resolveParameters(client, srcParameters);
+
+  // Step 4: resolve custom fields from target environment
+  const customFields = await resolveCustomFields(client, srcCustomFields);
+
+  const mappingDoc = {
+    useFqn: true,
+    mapping: { connections, parameters, customFields }
+  };
+
+  const outputFile = path.resolve(rawOpts.outputFile);
+  await mkdir(path.dirname(outputFile), { recursive: true });
+  await writeFile(outputFile, JSON.stringify(mappingDoc, null, 2), 'utf8');
+  log.info('Mapping file written', { outputFile });
+
+  const result = {
+    command: 'generate-mapping',
+    outputFile,
+    connections: connections.length,
+    parameters: parameters.length,
+    customFields: customFields.length
+  };
+  new Reporter(rawOpts.output || 'text').emit(result);
+}
+
+async function resolveConnections(client, srcConnections) {
+  if (srcConnections.length === 0) return [];
+
+  // Group source connections by connectorId
+  const byConnectorId = new Map();
+  for (const conn of srcConnections) {
+    if (!byConnectorId.has(conn.connectorId)) byConnectorId.set(conn.connectorId, []);
+    byConnectorId.get(conn.connectorId).push(conn);
+  }
+
+  const mappings = [];
+
+  for (const [connectorId, srcConns] of byConnectorId) {
+    log.info('Searching connections in target', { connectorId });
+
+    // Fetch all pages for this connectorId
+    const targetItems = await fetchAllPages(client, '/api/v1/connections/search', {
+      filter: [{ attribute: 'connectorId', operator: 'In', datatype: 'string', value: connectorId }]
+    }, `connections with connectorId=${connectorId}`);
+
+    for (const src of srcConns) {
+      const match = targetItems.find(
+        (t) => t.name.toLowerCase() === src.name.toLowerCase()
+      );
+      if (!match) {
+        throw new CliError(
+          `Connection "${src.name}" (connectorId: ${connectorId}) was not found in the target environment. ` +
+          `Ensure a connection with this name exists in the target workspace before generating the mapping.`
+        );
+      }
+      mappings.push({ existingId: src.id, newId: match.id, action: 'override' });
+      log.info('Mapped connection', { name: src.name, existingId: src.id, newId: match.id });
+    }
+  }
+
+  return mappings;
+}
+
+async function resolveParameters(client, srcParameters) {
+  if (srcParameters.length === 0) return [];
+
+  log.info('Searching parameters in target');
+
+  let targetItems = [];
+  try {
+    targetItems = await fetchAllPages(client, '/api/v1/parameters/search', {}, 'parameters');
+  } catch (err) {
+    if (err instanceof ApiError && err.code === 'ResultsNotFound') {
+      log.warn('No parameters found in target environment — mapping without newId');
+      return srcParameters.map((p) => ({ existingId: p.id, action: 'upsert' }));
+    }
+    throw err;
+  }
+
+  return srcParameters.map((src) => {
+    const match = targetItems.find(
+      (t) => t.name.toLowerCase() === src.name.toLowerCase()
+    );
+    if (!match) {
+      log.warn('Parameter not matched in target, mapping without newId', { name: src.name });
+      return { existingId: src.id, action: 'upsert' };
+    }
+    log.info('Mapped parameter', { name: src.name, existingId: src.id, newId: match.id });
+    return { existingId: src.id, newId: match.id, action: 'upsert' };
+  });
+}
+
+async function resolveCustomFields(client, srcCustomFields) {
+  if (srcCustomFields.length === 0) return [];
+
+  log.info('Fetching screens for custom field mapping');
+  const screens = await client.post('/api/v1/screens/default/search', ['rule', 'check']);
+
+  // Flatten all fields from all sections of all screens into a name→id map
+  const fieldMap = new Map();
+  for (const screen of Array.isArray(screens) ? screens : []) {
+    const sections = screen?.info?.sections || [];
+    for (const section of sections) {
+      for (const field of section.fields || []) {
+        if (field.name && field.id) {
+          fieldMap.set(field.name.toLowerCase(), field.id);
+        }
+      }
+    }
+  }
+
+  const mappings = [];
+  for (const fieldName of srcCustomFields) {
+    const targetId = fieldMap.get(fieldName.toLowerCase());
+    if (!targetId) {
+      log.warn('Custom field not found in target screens, skipping', { fieldName });
+      continue;
+    }
+    mappings.push({ existingId: fieldName, newId: targetId, action: 'override' });
+    log.info('Mapped custom field', { fieldName, newId: targetId });
+  }
+
+  return mappings;
+}
+
+// Fetches all pages from a paginated POST search endpoint.
+// Throws ApiError with code='ResultsNotFound' when the endpoint reports nothing found.
+async function fetchAllPages(client, endpoint, body, label) {
+  const items = [];
+  let pageNo = 1;
+  let totalPages = 1;
+
+  do {
+    const url = `${endpoint}?pageNo=${pageNo}&pageSize=${PAGE_SIZE}&sort=updatedTimestamp:desc`;
+    const resp = await client.post(url, body);
+
+    // API may return 200 with {code, message} instead of a 4xx
+    if (resp && resp.code === 'ResultsNotFound') {
+      throw new ApiError(`${label}: ${resp.message || 'ResultsNotFound'}`, {
+        status: 200,
+        code: 'ResultsNotFound'
+      });
+    }
+
+    items.push(...(resp?.items || []));
+    totalPages = resp?.pageable?.pages ?? 1;
+    pageNo++;
+  } while (pageNo <= totalPages);
+
+  return items;
+}

package/src/commands/import.js

@@ -1,175 +1,174 @@
-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`, {});
-}
+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 (mappingDoc.useFqn === undefined) {
+    mappingDoc.useFqn = !!rawOpts.useFqn;
+  }
+
+  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`, {});
+}