@kaddo/cli 3.80.0 → 3.82.0

package/dist/core.js

@@ -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),
@@ -8122,6 +8123,25 @@ function getWorkItem(dir, workItemId) {
   };
   return { ...detail, refinement: computeRefinementStatus(detail) };
 }
+function parseGraphReason(v) {
+  if (!v || typeof v !== "object") return null;
+  const o = v;
+  const relationship = typeof o.relationship === "string" && o.relationship.trim() ? o.relationship.trim() : null;
+  const path4 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
+  return relationship || path4.length ? { relationship, path: path4 } : null;
+}
+function parseExplain(o) {
+  const refs = Array.isArray(o.evidence) ? o.evidence : Array.isArray(o.evidence_refs) ? o.evidence_refs : [];
+  return {
+    reason: typeof o.reason === "string" && o.reason.trim() ? o.reason.trim() : null,
+    graphReason: parseGraphReason(o.graph_reason),
+    evidenceRefs: refs.map(String).filter(Boolean),
+    evidenceSummary: typeof o.evidence_summary === "string" && o.evidence_summary.trim() ? o.evidence_summary.trim() : null
+  };
+}
+function emptyExplain() {
+  return { reason: null, graphReason: null, evidenceRefs: [], evidenceSummary: null };
+}
 function parseSystemImpact(dir, fm) {
   const topology = loadSystemTopology(dir);
   const byId = new Map(topology.entities.map((e) => [e.id, e]));
@@ -8129,10 +8149,19 @@ function parseSystemImpact(dir, fm) {
     const e = byId.get(id);
     return { id, nodeId: `sys:${id}`, label: e?.label ?? id, kind: e?.kind ?? "unknown", moduleId: e?.moduleId ?? null };
   };
-  const affected = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(String).filter(Boolean).map(resolve) : [];
-  const reviewed = Array.isArray(fm.reviewed_system_entities) ? fm.reviewed_system_entities.filter((r) => Boolean(r) && typeof r === "object").map((r) => ({ ...resolve(String(r.id ?? "")), status: String(r.status ?? "unknown"), reason: r.reason ? String(r.reason) : null })).filter((r) => r.id) : [];
+  const affected = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map((raw) => {
+    if (typeof raw === "string") return raw ? { ...resolve(raw), ...emptyExplain() } : null;
+    if (raw && typeof raw === "object") {
+      const o = raw;
+      const id = String(o.id ?? "");
+      return id ? { ...resolve(id), ...parseExplain(o) } : null;
+    }
+    return null;
+  }).filter((e) => e != null) : [];
+  const reviewed = Array.isArray(fm.reviewed_system_entities) ? fm.reviewed_system_entities.filter((r) => Boolean(r) && typeof r === "object").map((r) => ({ ...resolve(String(r.id ?? "")), ...parseExplain(r), status: String(r.status ?? "unknown") })).filter((r) => r.id) : [];
   const graphRevision = typeof fm.graph_revision === "string" && fm.graph_revision.trim() ? fm.graph_revision.trim() : null;
-  return { affectedSystemEntities: affected, reviewedSystemEntities: reviewed, graphRevision };
+  const graphCoverage = topology.entities.length === 0 ? "unavailable" : topology.relationships.length > 0 ? "available" : "partial";
+  return { affectedSystemEntities: affected, reviewedSystemEntities: reviewed, graphRevision, graphCoverage };
 }
 function readBody(filePath) {
   try {
@@ -8806,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,
@@ -8813,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
@@ -8890,7 +8920,8 @@ function validateWorkItem(dir, id) {
   const topology = loadSystemTopology(dir);
   const entityById = new Map(topology.entities.map((e) => [e.id, e]));
   const fm = data;
-  const affectedEntities = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(String) : [];
+  const idOf = (raw2) => typeof raw2 === "string" ? raw2 : raw2 && typeof raw2 === "object" ? String(raw2.id ?? "") : "";
+  const affectedEntities = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(idOf).filter(Boolean) : [];
   for (const eid of affectedEntities) {
     const e = entityById.get(eid);
     if (!e) {
@@ -9276,11 +9307,12 @@ function buildRefinementHandoff(dir, workItemId) {
   const lines = [
     `Refine Work Item ${wi.id} \u2014 "${wi.title}" \u2014 in project "${projectName}" using Kaddo.`,
     "",
-    "Use a Kaddo-enabled agent with access to this repository. Drive the refinement with the",
-    `canonical ${RECOMMENDED_AGENT} and the ${RECOMMENDED_SKILL} skill (via Kaddo MCP or skills).`,
+    `Use the canonical ${RECOMMENDED_AGENT} and the ${RECOMMENDED_SKILL} skill (via Kaddo MCP or skills),`,
+    "with access to this repository.",
     "",
-    "Inspect the actual implementation before defining scope \u2014 do not guess affected modules from",
-    "the Work Item title. Read the current behavior in the code first, then classify."
+    "Inspect the actual implementation and the relevant mapped modules before defining the final scope \u2014",
+    "do not guess affected modules from the Work Item title. Read the current behavior in the code first,",
+    "then classify."
   ];
   if (multirepo) {
     lines.push(
@@ -9293,15 +9325,23 @@ function buildRefinementHandoff(dir, workItemId) {
   if (topology !== "unavailable") {
     lines.push(
       "",
-      `The semantic system Graph is ${topology}. Identify the relevant system entry points, then use`,
-      "the Kaddo Graph (search / neighbors / paths) to find connected components, dependencies, APIs,",
-      "datastores and external systems. Treat Graph-derived entities as IMPACT CANDIDATES, not",
-      "confirmed scope: inspect each candidate in the repository and classify it as affected,",
-      "reviewed-not-affected or unknown, preserving the reason/evidence. A missing Graph edge does not",
-      "mean no impact \u2014 especially when coverage is partial."
+      `The semantic system Graph is ${topology}. When semantic system topology is available:`,
+      "1. identify the relevant system entry points;",
+      "2. query the Kaddo Graph (search / neighbors / paths) for connected entities;",
+      "3. treat Graph results as IMPACT CANDIDATES, not confirmed scope;",
+      "4. inspect the actual implementation in the repository for each relevant candidate;",
+      "5. classify each candidate as affected, reviewed-not-affected or unknown;",
+      "6. preserve the evidence and reasons behind each classification.",
+      "",
+      "A missing Graph relationship does not mean no impact, especially when Graph coverage is partial \u2014",
+      "keep inspecting the repository beyond the Graph candidates when the task requires it."
     );
   } else {
-    lines.push("", "The semantic system Graph is not available yet; refine using the repository and Knowledge.");
+    lines.push(
+      "",
+      "The semantic system Graph is unavailable. Continue repository-driven refinement normally, using the",
+      "repository, Knowledge and mapped modules \u2014 the Graph is enrichment, not a prerequisite."
+    );
   }
   lines.push(
     "",
@@ -9328,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,
@@ -9347,7 +9842,9 @@ export {
   discoverKnowledge,
   discoverWorkItems,
   exists,
+  findLinkedWorkItem,
   findSystemPaths,
+  getExternalWorkItem,
   getImpactCandidates,
   getSystemMapProjection,
   getSystemNeighbors,
@@ -9357,15 +9854,20 @@ export {
   getWorkItemForEdit,
   getWorkItems,
   getWorkItemsSummary,
+  importExternalWorkItem,
+  integrationRegistry,
   isActiveState,
   isModule,
   join,
   knowledgeLayers,
   lifecycleCounts,
   lifecycleStateOf,
+  listExternalWorkItems,
+  listIntegrations,
   loadConfig,
   loadMappedModules,
   loadSystemTopology,
+  previewImport,
   readFile,
   searchSystemNodes,
   topologyRevision,
@@ -9373,5 +9875,6 @@ export {
   updateWorkItem,
   validateSystemTopology,
   validateTopologyProposal,
-  validateWorkItem
+  validateWorkItem,
+  verifyIntegration
 };