npm - @kaddo/cli - Versions diffs - 3.81.0 → 3.82.0 - Mend

@kaddo/cli 3.81.0 → 3.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/admin-dist/assets/index-DIfpc20n.js +44 -0
package/dist/admin-dist/index.html +1 -1
package/dist/admin-server/index.js +98 -0
package/dist/core.js +467 -2
package/dist/index.js +839 -57
package/package.json +1 -1
package/dist/admin-dist/assets/index-xgxqXGxn.js +0 -44

package/dist/admin-dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>admin</title>
-    <script type="module" crossorigin src="/assets/index-xgxqXGxn.js"></script>
+    <script type="module" crossorigin src="/assets/index-DIfpc20n.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DNkI-1xG.css">
   </head>
   <body>

package/dist/admin-server/index.js CHANGED Viewed

@@ -70,6 +70,14 @@ import {
   buildRefinementHandoff as coreBuildRefinementHandoff,
   getSystemMapProjection as coreGetSystemMapProjection,
   buildTopologyEnrichmentHandoff as coreBuildTopologyHandoff,
+  listIntegrations as coreListIntegrations,
+  verifyIntegration as coreVerifyIntegration,
+  listExternalWorkItems as coreListExternalWorkItems,
+  getExternalWorkItem as coreGetExternalWorkItem,
+  previewImport as corePreviewImport,
+  importExternalWorkItem as coreImportExternalWorkItem,
+  IntegrationError,
+  IntegrationServiceError,
   WorkItemWriteError,
   exists,
   join,
@@ -335,6 +343,58 @@ var CoreError = class extends Error {
   }
   code;
 };
+function mapIntegrationError(err) {
+  if (err instanceof IntegrationError) throw new CoreError(err.code, err.safeMessage);
+  if (err instanceof IntegrationServiceError) throw new CoreError(err.code, err.message);
+  throw err;
+}
+function assertExternalId(externalId) {
+  if (!externalId || externalId.includes("/") || externalId.includes("\\") || externalId.includes("..")) {
+    throw new CoreError("INVALID_EXTERNAL_ID", "Invalid external work item identifier.");
+  }
+}
+function getIntegrations(dir) {
+  return coreListIntegrations(dir);
+}
+async function getIntegrationStatus(dir, id) {
+  try {
+    return await coreVerifyIntegration(dir, id);
+  } catch (err) {
+    mapIntegrationError(err);
+  }
+}
+async function getExternalWorkItems(dir, id, opts) {
+  try {
+    return await coreListExternalWorkItems(dir, id, { cursor: opts.cursor, pageSize: opts.pageSize, filters: { status: opts.status, query: opts.query } });
+  } catch (err) {
+    mapIntegrationError(err);
+  }
+}
+async function getExternalWorkItemDetail(dir, id, externalId) {
+  assertExternalId(externalId);
+  try {
+    return await coreGetExternalWorkItem(dir, id, externalId);
+  } catch (err) {
+    mapIntegrationError(err);
+  }
+}
+async function previewIntegrationImport(dir, id, externalId, opts) {
+  assertExternalId(externalId);
+  try {
+    return await corePreviewImport(dir, id, externalId, { type: opts.type });
+  } catch (err) {
+    mapIntegrationError(err);
+  }
+}
+async function importIntegrationWorkItem(dir, id, externalId, opts) {
+  assertExternalId(externalId);
+  try {
+    return await coreImportExternalWorkItem(dir, id, externalId, { type: opts.type });
+  } catch (err) {
+    if (err instanceof WorkItemWriteError) throw new CoreError(err.code, err.message);
+    mapIntegrationError(err);
+  }
+}
 // src/contracts/schemas.ts
 import { z } from "zod";
@@ -827,6 +887,44 @@ async function createAdminServer(opts) {
   app.get("/api/v1/admin/findings", coreRoute(getFindings));
   app.get("/api/v1/admin/system", coreRoute(getSystemMap));
   app.get("/api/v1/admin/system/topology-handoff", coreRoute(getTopologyHandoff));
+  const asyncCore = async (reply, fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof CoreError) return reply.code(statusForCode(err.code)).send({ error: { code: err.code, message: err.message } });
+      throw err;
+    }
+  };
+  app.get("/api/v1/admin/integrations", coreRoute(getIntegrations));
+  app.get(
+    "/api/v1/admin/integrations/:id/status",
+    async (request, reply) => asyncCore(reply, () => getIntegrationStatus(projectDir, request.params.id))
+  );
+  app.get(
+    "/api/v1/admin/integrations/:id/work-items",
+    async (request, reply) => asyncCore(reply, () => getExternalWorkItems(projectDir, request.params.id, {
+      cursor: request.query.cursor,
+      pageSize: request.query.pageSize ? Number.parseInt(request.query.pageSize, 10) : void 0,
+      status: request.query.status,
+      query: request.query.query
+    }))
+  );
+  app.get(
+    "/api/v1/admin/integrations/:id/work-items/:externalId",
+    async (request, reply) => asyncCore(reply, () => getExternalWorkItemDetail(projectDir, request.params.id, request.params.externalId))
+  );
+  app.get(
+    "/api/v1/admin/integrations/:id/work-items/:externalId/import-preview",
+    async (request, reply) => asyncCore(reply, () => previewIntegrationImport(projectDir, request.params.id, request.params.externalId, { type: request.query.type }))
+  );
+  app.post(
+    "/api/v1/admin/integrations/:id/work-items/:externalId/import",
+    async (request, reply) => {
+      const type = request.body?.type;
+      if (!type) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "A Kaddo Work Item type is required to import." } });
+      return asyncCore(reply, () => importIntegrationWorkItem(projectDir, request.params.id, request.params.externalId, { type }));
+    }
+  );
   app.get("/api/v1/admin/knowledge/inventory", coreRoute(getKnowledgeInventory));
   app.get("/api/v1/admin/knowledge/artifact/:artifactId", async (request) => {
     try {

package/dist/core.js CHANGED Viewed

@@ -6583,6 +6583,7 @@ function parseWorkItemSource(frontmatter) {
       title: optStr(obj.title) ?? optStr(frontmatter.source_title),
       context: optStr(obj.context) ?? optStr(frontmatter.source_context),
       provider: optStr(obj.provider) ?? optStr(frontmatter.source_provider),
+      integration: optStr(obj.integration) ?? optStr(frontmatter.source_integration),
       url: optStr(obj.url) ?? optStr(frontmatter.source_url),
       imported_at: optStr(obj.imported_at) ?? optStr(frontmatter.source_imported_at),
       synced_at: optStr(obj.synced_at) ?? optStr(frontmatter.source_synced_at),
@@ -8834,6 +8835,7 @@ function createWorkItem(dir, opts) {
   const id = nextWorkItemId(dir);
   const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
   const data = {
     type,
     id,
@@ -8841,7 +8843,7 @@ function createWorkItem(dir, opts) {
     status: "draft",
     work_type: type,
     created_at: today,
-    source: { type: "manual", inferred: false },
+    source,
     generated_by: "kaddo-admin",
     affected_modules: [],
     summary: intent
@@ -9366,7 +9368,462 @@ function buildRefinementHandoff(dir, workItemId) {
     text: lines.join("\n")
   };
 }
+// src/services/integrations.ts
+import matter8 from "gray-matter";
+import { parse as parseYaml9 } from "yaml";
+// ../integrations/src/errors.ts
+var RETRYABLE = /* @__PURE__ */ new Set([
+  "INTEGRATION_RATE_LIMITED",
+  "INTEGRATION_UNAVAILABLE",
+  "INTEGRATION_TIMEOUT"
+]);
+var IntegrationError = class extends Error {
+  code;
+  /** True for transient conditions (rate limit / unavailable / timeout). */
+  retryable;
+  /** A safe, provider-agnostic reason. Never the raw SDK message. */
+  safeMessage;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationError";
+    this.code = code;
+    this.retryable = RETRYABLE.has(code);
+    this.safeMessage = message;
+  }
+};
+function defaultMessageFor(code) {
+  switch (code) {
+    case "INTEGRATION_CONFIG_INVALID":
+      return "The integration configuration is invalid.";
+    case "INTEGRATION_UNAUTHORIZED":
+      return "Authentication failed. Check the configured credentials.";
+    case "INTEGRATION_FORBIDDEN":
+      return "The configured credentials lack permission for this operation.";
+    case "INTEGRATION_NOT_FOUND":
+      return "The requested external resource was not found.";
+    case "INTEGRATION_RATE_LIMITED":
+      return "The external provider is rate limiting requests. Try again later.";
+    case "INTEGRATION_UNAVAILABLE":
+      return "The external provider is temporarily unavailable.";
+    case "INTEGRATION_TIMEOUT":
+      return "The external provider did not respond in time.";
+    case "INTEGRATION_PROVIDER_ERROR":
+      return "The external provider returned an error.";
+    case "UNSUPPORTED_CAPABILITY":
+      return "This adapter does not support the requested capability.";
+  }
+}
+function integrationError(code, message) {
+  return new IntegrationError(code, message ?? defaultMessageFor(code));
+}
+// ../integrations/src/identity.ts
+function externalIdentityKey(integrationId, externalId) {
+  return `${integrationId}#${externalId}`;
+}
+function externalDisplayKey(provider, externalId) {
+  return `${provider}#${externalId}`;
+}
+// ../integrations/src/config.ts
+var ENV_SUFFIX = "_env";
+var SECRET_KEY = /(token|secret|password|key|pat|apikey|api_key)/i;
+function parseCredentials(raw, id, findings) {
+  const creds = {};
+  if (raw == null) return creds;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    findings.push({ level: "blocking", id, message: `Integration "${id}": credentials must be a mapping of secret references.` });
+    return creds;
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.endsWith(ENV_SUFFIX)) {
+      const name = key.slice(0, -ENV_SUFFIX.length);
+      if (typeof value === "string" && value.trim()) creds[name] = { env: value.trim() };
+      else findings.push({ level: "blocking", id, message: `Integration "${id}": credential "${key}" must name an environment variable.` });
+      continue;
+    }
+    if (SECRET_KEY.test(key) && typeof value === "string") {
+      findings.push({ level: "blocking", id, message: `Integration "${id}": secret "${key}" must not be stored in config. Use "${key}${ENV_SUFFIX}: <ENV_VAR_NAME>".` });
+      continue;
+    }
+    if (value && typeof value === "object" && typeof value.env === "string") {
+      creds[key] = { env: String(value.env) };
+      continue;
+    }
+    findings.push({ level: "warning", id, message: `Integration "${id}": ignoring unrecognized credential entry "${key}".` });
+  }
+  return creds;
+}
+function parseIntegrationsConfig(raw, opts) {
+  const findings = [];
+  const integrations = [];
+  const list2 = raw && typeof raw === "object" && Array.isArray(raw.integrations) ? raw.integrations : Array.isArray(raw) ? raw : [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list2) {
+    if (!entry || typeof entry !== "object") {
+      findings.push({ level: "blocking", message: "Each integration must be a mapping." });
+      continue;
+    }
+    const o = entry;
+    const id = typeof o.id === "string" ? o.id.trim() : "";
+    const adapter = typeof o.adapter === "string" ? o.adapter.trim() : "";
+    if (!id) {
+      findings.push({ level: "blocking", message: 'An integration is missing a required "id".' });
+      continue;
+    }
+    if (seen.has(id)) {
+      findings.push({ level: "blocking", id, message: `Duplicate integration id "${id}".` });
+      continue;
+    }
+    seen.add(id);
+    if (!adapter) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" is missing a required "adapter".` });
+      continue;
+    }
+    if (!opts.adapterIds.has(adapter)) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" references unknown adapter "${adapter}".` });
+    }
+    const enabled = o.enabled === void 0 ? true : o.enabled === true || o.enabled === "true";
+    const config = o.config && typeof o.config === "object" && !Array.isArray(o.config) ? o.config : {};
+    const credentials = parseCredentials(o.credentials, id, findings);
+    const timeoutMs = typeof o.timeout_ms === "number" ? o.timeout_ms : typeof o.timeoutMs === "number" ? o.timeoutMs : void 0;
+    integrations.push({ id, adapter, enabled, config, credentials, timeoutMs });
+  }
+  return { integrations, findings };
+}
+function resolveCredentials(integration, env) {
+  const credentials = {};
+  const missing = [];
+  for (const [name, ref] of Object.entries(integration.credentials)) {
+    const value = env[ref.env];
+    if (value && value.length > 0) credentials[name] = value;
+    else missing.push(ref.env);
+  }
+  return { credentials, missing };
+}
+// ../integrations/src/preview.ts
+function buildImportPreview(item, opts) {
+  return {
+    source: {
+      provider: item.provider,
+      integration: opts.integrationId,
+      externalId: item.externalId,
+      url: item.url,
+      identityKey: externalIdentityKey(opts.integrationId, item.externalId),
+      displayKey: externalDisplayKey(item.provider, item.externalId)
+    },
+    capturedIntent: item.title,
+    description: item.description,
+    externalType: item.type,
+    externalStatus: item.status,
+    kaddoStatus: "draft",
+    kaddoType: opts.type ? opts.type : null,
+    writes: false
+  };
+}
+// ../integrations/src/registry.ts
+var DuplicateAdapterError = class extends Error {
+  constructor(id) {
+    super(`An integration adapter with id "${id}" is already registered.`);
+    this.name = "DuplicateAdapterError";
+  }
+};
+var IntegrationRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    if (this.adapters.has(adapter.id)) throw new DuplicateAdapterError(adapter.id);
+    this.adapters.set(adapter.id, adapter);
+  }
+  get(id) {
+    return this.adapters.get(id);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  list() {
+    return [...this.adapters.values()].sort((a, b) => a.id.localeCompare(b.id));
+  }
+  ids() {
+    return new Set(this.adapters.keys());
+  }
+};
+// ../integrations/src/mock-adapter.ts
+var MOCK_ADAPTER_ID = "mock";
+var DEFAULT_ITEMS = [
+  {
+    externalId: "EXT-001",
+    provider: MOCK_ADAPTER_ID,
+    title: "Open public registration to everyone",
+    description: "Open self-service registration to the public once the private beta ends.",
+    type: "Feature",
+    status: "Open",
+    url: "https://example.test/mock/EXT-001",
+    labels: ["registration", "beta"],
+    createdAt: "2026-01-05T10:00:00.000Z",
+    updatedAt: "2026-02-01T09:30:00.000Z",
+    rawMetadata: { board: "delivery" }
+  },
+  {
+    externalId: "EXT-002",
+    provider: MOCK_ADAPTER_ID,
+    title: "Personalize onboarding steps",
+    description: "The onboarding checklist should adapt to what the user has already completed.",
+    type: "Task",
+    status: "To Do",
+    url: "https://example.test/mock/EXT-002",
+    labels: ["onboarding"],
+    createdAt: "2026-01-08T12:00:00.000Z",
+    updatedAt: "2026-01-20T15:00:00.000Z"
+  }
+];
+function simulationOf(context, fallback) {
+  const fromConfig = context.config?.simulate;
+  return typeof fromConfig === "string" ? fromConfig : fallback;
+}
+function readFailure(sim) {
+  switch (sim) {
+    case "unauthorized":
+      throw integrationError("INTEGRATION_UNAUTHORIZED");
+    case "rate-limited":
+      throw integrationError("INTEGRATION_RATE_LIMITED");
+    case "unavailable":
+      throw integrationError("INTEGRATION_UNAVAILABLE");
+    case "timeout":
+      throw integrationError("INTEGRATION_TIMEOUT");
+    case "available":
+      break;
+  }
+}
+function createMockAdapter(opts = {}) {
+  const items = opts.items ?? DEFAULT_ITEMS;
+  const defaultSim = opts.simulate ?? "available";
+  const defaultPageSize = opts.pageSize ?? 50;
+  return {
+    id: MOCK_ADAPTER_ID,
+    metadata: {
+      id: MOCK_ADAPTER_ID,
+      displayName: "Mock Work Source",
+      version: "1.0.0",
+      description: "Deterministic offline reference adapter for validating the integration foundation."
+    },
+    capabilities: {
+      workItems: { list: true, read: true, import: true, write: false, statusSync: false, comments: false, webhooks: false }
+    },
+    async verifyConnection(context) {
+      const sim = simulationOf(context, defaultSim);
+      const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+      switch (sim) {
+        case "available":
+          return { status: "available", checkedAt };
+        case "unauthorized":
+          return { status: "unauthorized", message: "Check the configured credentials.", checkedAt };
+        case "rate-limited":
+        case "unavailable":
+        case "timeout":
+          return { status: "unavailable", message: "The mock provider is temporarily unavailable.", checkedAt };
+      }
+    },
+    async listWorkItems(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      let pool = items;
+      const f = request.filters;
+      if (f?.status) pool = pool.filter((i) => (i.status ?? "").toLowerCase() === f.status.toLowerCase());
+      if (f?.query) pool = pool.filter((i) => `${i.title} ${i.description ?? ""}`.toLowerCase().includes(f.query.toLowerCase()));
+      if (f?.updatedSince) pool = pool.filter((i) => (i.updatedAt ?? "") >= f.updatedSince);
+      const size = Math.max(1, request.pageSize ?? defaultPageSize);
+      const start = request.cursor ? Math.max(0, Number.parseInt(request.cursor, 10) || 0) : 0;
+      const slice = pool.slice(start, start + size);
+      const end = start + slice.length;
+      const hasMore = end < pool.length;
+      return { items: slice, hasMore, ...hasMore ? { nextCursor: String(end) } : {} };
+    },
+    async getWorkItem(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      return items.find((i) => i.externalId === request.externalId) ?? null;
+    }
+  };
+}
+// ../integrations/src/index.ts
+function createDefaultRegistry() {
+  const registry2 = new IntegrationRegistry();
+  registry2.register(createMockAdapter());
+  return registry2;
+}
+// src/services/integrations.ts
+var INTEGRATIONS_FILE = ".kaddo/integrations.yml";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var registry = createDefaultRegistry();
+function integrationRegistry() {
+  return registry;
+}
+var IntegrationServiceError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationServiceError";
+    this.code = code;
+  }
+};
+function loadRaw(dir) {
+  const abs = join(dir, INTEGRATIONS_FILE);
+  if (!exists(abs)) return { integrations: [] };
+  try {
+    return parseYaml9(readFile(abs)) ?? { integrations: [] };
+  } catch {
+    return { integrations: [] };
+  }
+}
+function loadIntegrations(dir) {
+  return parseIntegrationsConfig(loadRaw(dir), { adapterIds: registry.ids() });
+}
+function configStatus(integration, findings) {
+  if (!integration.enabled) return "disabled";
+  const blocking = findings.some((f) => f.id === integration.id && f.level === "blocking");
+  if (blocking || !registry.has(integration.adapter)) return "invalid-config";
+  return "configured";
+}
+function listIntegrations(dir) {
+  const { integrations, findings } = loadIntegrations(dir);
+  return integrations.map((integration) => {
+    const adapter = registry.get(integration.adapter);
+    return {
+      id: integration.id,
+      adapter: integration.adapter,
+      enabled: integration.enabled,
+      status: configStatus(integration, findings),
+      displayName: adapter?.metadata.displayName ?? integration.adapter,
+      capabilities: adapter?.capabilities ?? null,
+      metadata: adapter?.metadata ?? null,
+      credentialRefs: Object.values(integration.credentials).map((c) => c.env),
+      findings: findings.filter((f) => f.id === integration.id)
+    };
+  });
+}
+function requireIntegration(dir, id) {
+  const { integrations, findings } = loadIntegrations(dir);
+  const integration = integrations.find((i) => i.id === id);
+  if (!integration) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured in this project.`);
+  return { integration, findings };
+}
+function resolveAdapter(integration) {
+  const adapter = registry.get(integration.adapter);
+  if (!adapter) throw new IntegrationServiceError("ADAPTER_NOT_FOUND", `Unknown integration adapter "${integration.adapter}".`);
+  return adapter;
+}
+function buildContext(integration, env) {
+  const { credentials, missing } = resolveCredentials(integration, env);
+  return {
+    context: { integrationId: integration.id, config: integration.config, credentials, timeoutMs: integration.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+    missing
+  };
+}
+async function withTimeout(op, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(integrationError("INTEGRATION_TIMEOUT")), ms);
+  });
+  try {
+    return await Promise.race([op, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function verifyIntegration(dir, id, env = process.env) {
+  const { integration, findings } = requireIntegration(dir, id);
+  const cfgStatus = configStatus(integration, findings);
+  if (cfgStatus === "disabled") return { id, status: "disabled", connection: null, missingCredentials: [] };
+  if (cfgStatus === "invalid-config") return { id, status: "invalid-config", connection: null, missingCredentials: [] };
+  const adapter = resolveAdapter(integration);
+  const { context, missing } = buildContext(integration, env);
+  try {
+    const connection = await withTimeout(adapter.verifyConnection(context), context.timeoutMs);
+    return { id, status: statusOf(connection), connection, missingCredentials: missing, message: connection.message };
+  } catch (err) {
+    const e = err instanceof IntegrationError ? err : integrationError("INTEGRATION_PROVIDER_ERROR");
+    return { id, status: e.code === "INTEGRATION_UNAUTHORIZED" ? "unauthorized" : "unavailable", connection: null, missingCredentials: missing, message: e.safeMessage };
+  }
+}
+function statusOf(connection) {
+  switch (connection.status) {
+    case "available":
+      return "available";
+    case "unauthorized":
+      return "unauthorized";
+    case "unavailable":
+      return "unavailable";
+    case "invalid-config":
+      return "invalid-config";
+  }
+}
+async function listExternalWorkItems(dir, id, opts = {}, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.list) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot list work items.`);
+  const { context } = buildContext(integration, env);
+  return withTimeout(adapter.listWorkItems({ context, cursor: opts.cursor, pageSize: opts.pageSize, filters: opts.filters }), context.timeoutMs);
+}
+async function getExternalWorkItem(dir, id, externalId, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.read) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot read work items.`);
+  const { context } = buildContext(integration, env);
+  return withTimeout(adapter.getWorkItem({ context, externalId }), context.timeoutMs);
+}
+function findLinkedWorkItem(dir, integrationId, externalId) {
+  for (const art of discoverWorkItems(dir)) {
+    let data;
+    try {
+      data = matter8(readFile(art.filePath)).data;
+    } catch {
+      continue;
+    }
+    const source = parseWorkItemSource(data);
+    if (source.integration === integrationId && source.id === externalId) {
+      return { workItemId: String(data.id ?? ""), title: String(data.title ?? "") };
+    }
+  }
+  return null;
+}
+async function previewImport(dir, id, externalId, opts = {}, env = process.env) {
+  const item = await getExternalWorkItem(dir, id, externalId, env);
+  if (!item) throw integrationError("INTEGRATION_NOT_FOUND", `External work item "${externalId}" was not found.`);
+  const preview = buildImportPreview(item, { integrationId: id, type: opts.type });
+  return { preview, duplicate: findLinkedWorkItem(dir, id, externalId) };
+}
+async function importExternalWorkItem(dir, id, externalId, opts, env = process.env) {
+  const item = await getExternalWorkItem(dir, id, externalId, env);
+  if (!item) throw integrationError("INTEGRATION_NOT_FOUND", `External work item "${externalId}" was not found.`);
+  const preview = buildImportPreview(item, { integrationId: id, type: opts.type });
+  const existing = findLinkedWorkItem(dir, id, externalId);
+  if (existing) return { workItemId: existing.workItemId, created: false, duplicateOf: existing.workItemId, preview };
+  const intent = item.description ? `${item.title}
+${item.description}` : item.title;
+  const created = createWorkItem(dir, {
+    intent,
+    type: opts.type,
+    source: {
+      type: "external",
+      provider: item.provider,
+      integration: id,
+      id: externalId,
+      url: item.url,
+      imported_at: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  });
+  return { workItemId: created.id, created: true, preview, path: created.path };
+}
 export {
+  INTEGRATIONS_FILE,
+  IntegrationError,
+  IntegrationServiceError,
   TOPOLOGY_FILE,
   TopologyWriteError,
   WorkItemNotFoundError,
@@ -9385,7 +9842,9 @@ export {
   discoverKnowledge,
   discoverWorkItems,
   exists,
+  findLinkedWorkItem,
   findSystemPaths,
+  getExternalWorkItem,
   getImpactCandidates,
   getSystemMapProjection,
   getSystemNeighbors,
@@ -9395,15 +9854,20 @@ export {
   getWorkItemForEdit,
   getWorkItems,
   getWorkItemsSummary,
+  importExternalWorkItem,
+  integrationRegistry,
   isActiveState,
   isModule,
   join,
   knowledgeLayers,
   lifecycleCounts,
   lifecycleStateOf,
+  listExternalWorkItems,
+  listIntegrations,
   loadConfig,
   loadMappedModules,
   loadSystemTopology,
+  previewImport,
   readFile,
   searchSystemNodes,
   topologyRevision,
@@ -9411,5 +9875,6 @@ export {
   updateWorkItem,
   validateSystemTopology,
   validateTopologyProposal,
-  validateWorkItem
+  validateWorkItem,
+  verifyIntegration
 };