@kaddo/cli 3.81.0 → 3.83.0

package/dist/core.js

@@ -7,6 +7,10 @@ function exists(p2) {
 function readFile(p2) {
   return fs.readFileSync(p2, "utf-8");
 }
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf-8");
+}
 function readDir(dirPath) {
   if (!exists(dirPath)) return [];
   return fs.readdirSync(dirPath);
@@ -6583,6 +6587,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 +8839,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 +8847,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 +9372,760 @@ function buildRefinementHandoff(dir, workItemId) {
     text: lines.join("\n")
   };
 }
+
+// src/services/integrations.ts
+import matter8 from "gray-matter";
+import { parse as parseYaml9, stringify as stringifyYaml5 } 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 parseSecrets(raw, id, findings) {
+  const secrets = {};
+  if (raw == null) return secrets;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    findings.push({ level: "blocking", id, message: `Integration "${id}": secrets must be a mapping of logical references.` });
+    return secrets;
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string" && value.trim()) {
+      if (value.length > 100 || /^(ghp_|sk-|xox[bpsa]-|glpat-|ey[A-Za-z0-9])/i.test(value)) {
+        findings.push({ level: "blocking", id, message: `Integration "${id}": secret "${key}" appears to contain an actual credential, not a reference name.` });
+        continue;
+      }
+      secrets[key] = value.trim();
+    } else {
+      findings.push({ level: "warning", id, message: `Integration "${id}": ignoring non-string secret entry "${key}".` });
+    }
+  }
+  return secrets;
+}
+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 secrets = parseSecrets(o.secrets, 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, secrets, timeoutMs });
+  }
+  return { integrations, findings };
+}
+async function resolveAllCredentials(integration, resolver, 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);
+  }
+  for (const [name, ref] of Object.entries(integration.secrets)) {
+    if (credentials[name]) continue;
+    const value = await resolver.resolve(ref);
+    if (value !== void 0) credentials[name] = value;
+    else missing.push(ref);
+  }
+  return { credentials, missing };
+}
+function serializeIntegrationsConfig(integrations) {
+  return {
+    integrations: integrations.map((i) => {
+      const entry = {
+        id: i.id,
+        adapter: i.adapter,
+        enabled: i.enabled
+      };
+      if (Object.keys(i.config).length > 0) entry.config = i.config;
+      if (Object.keys(i.credentials).length > 0) {
+        const creds = {};
+        for (const [name, ref] of Object.entries(i.credentials)) {
+          creds[`${name}${ENV_SUFFIX}`] = ref.env;
+        }
+        entry.credentials = creds;
+      }
+      if (Object.keys(i.secrets).length > 0) entry.secrets = i.secrets;
+      if (i.timeoutMs !== void 0) entry.timeout_ms = i.timeoutMs;
+      return entry;
+    })
+  };
+}
+function integrationConfigFromInput(input) {
+  return {
+    id: input.id,
+    adapter: input.adapter,
+    enabled: input.enabled ?? true,
+    config: input.config ?? {},
+    credentials: {},
+    secrets: input.secrets ?? {},
+    timeoutMs: input.timeoutMs
+  };
+}
+
+// ../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/secrets.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, existsSync as existsSync2, unlinkSync } from "fs";
+import { dirname as dirname2 } from "path";
+function secretRefKey(integrationId, secretName) {
+  return `${integrationId}.${secretName}`;
+}
+var SECRETS_FILENAME = ".secrets.json";
+function secretsPath(projectDir) {
+  return `${projectDir}/.kaddo/${SECRETS_FILENAME}`;
+}
+function loadStore(filePath) {
+  if (!existsSync2(filePath)) return {};
+  try {
+    const raw = readFileSync2(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch {
+    return {};
+  }
+}
+function saveStore(filePath, store) {
+  mkdirSync(dirname2(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+function createLocalSecretProvider(projectDir) {
+  const fp = secretsPath(projectDir);
+  return {
+    async get(key) {
+      const store = loadStore(fp);
+      const val = store[key];
+      return val !== void 0 && val !== "" ? val : void 0;
+    },
+    async set(key, value) {
+      const store = loadStore(fp);
+      store[key] = value;
+      saveStore(fp, store);
+    },
+    async delete(key) {
+      const store = loadStore(fp);
+      delete store[key];
+      saveStore(fp, store);
+    },
+    async exists(key) {
+      const store = loadStore(fp);
+      return key in store && store[key] !== void 0 && store[key] !== "";
+    }
+  };
+}
+function createEnvSecretProvider(env = process.env) {
+  return {
+    async get(key) {
+      const val = env[key];
+      return val !== void 0 && val !== "" ? val : void 0;
+    },
+    async set() {
+      throw new Error("Environment secret provider is read-only.");
+    },
+    async delete() {
+      throw new Error("Environment secret provider is read-only.");
+    },
+    async exists(key) {
+      const val = env[key];
+      return val !== void 0 && val !== "";
+    }
+  };
+}
+function createCompositeResolver(...providers) {
+  return {
+    async resolve(reference) {
+      for (const provider of providers) {
+        const val = await provider.get(reference);
+        if (val !== void 0) return val;
+      }
+      return void 0;
+    }
+  };
+}
+
+// ../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.",
+      configSchema: {
+        simulate: {
+          type: "select",
+          required: false,
+          label: "Simulation mode",
+          description: "Controls what the mock adapter simulates during verify/read operations.",
+          options: [
+            { value: "available", label: "Available" },
+            { value: "unauthorized", label: "Unauthorized" },
+            { value: "rate-limited", label: "Rate Limited" },
+            { value: "unavailable", label: "Unavailable" },
+            { value: "timeout", label: "Timeout" }
+          ],
+          defaultValue: "available"
+        }
+      },
+      secretSchema: {
+        token: {
+          type: "string",
+          required: false,
+          label: "API Token",
+          description: "Optional token for testing secret handling (not used by the mock adapter)."
+        }
+      }
+    },
+    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 saveIntegrations(dir, integrations) {
+  const abs = join(dir, INTEGRATIONS_FILE);
+  const data = serializeIntegrationsConfig(integrations);
+  writeFile(abs, stringifyYaml5(data, { lineWidth: 120 }));
+}
+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 secretProvider(dir) {
+  return createLocalSecretProvider(dir);
+}
+function secretResolver(dir, env) {
+  return createCompositeResolver(createLocalSecretProvider(dir), createEnvSecretProvider(env));
+}
+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),
+      secretRefs: Object.values(integration.secrets),
+      secretStatus: {},
+      findings: findings.filter((f) => f.id === integration.id)
+    };
+  });
+}
+function getIntegration(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.`);
+  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),
+    secretRefs: Object.values(integration.secrets),
+    secretStatus: {},
+    findings: findings.filter((f) => f.id === integration.id)
+  };
+}
+async function getIntegrationSecretStatus(dir, id) {
+  const { integrations } = loadIntegrations(dir);
+  const integration = integrations.find((i) => i.id === id);
+  if (!integration) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured.`);
+  const sp = secretProvider(dir);
+  const status = {};
+  for (const [name, ref] of Object.entries(integration.secrets)) {
+    status[name] = await sp.exists(ref);
+  }
+  for (const [name, ref] of Object.entries(integration.credentials)) {
+    const val = process.env[ref.env];
+    status[name] = val !== void 0 && val !== "";
+  }
+  return status;
+}
+function getAvailableIntegrationTypes() {
+  return registry.list().map((a) => ({
+    id: a.id,
+    displayName: a.metadata.displayName,
+    description: a.metadata.description,
+    configSchema: a.metadata.configSchema ?? {},
+    secretSchema: a.metadata.secretSchema ?? {},
+    capabilities: a.capabilities
+  }));
+}
+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, all: integrations };
+}
+function resolveAdapter(integration) {
+  const adapter = registry.get(integration.adapter);
+  if (!adapter) throw new IntegrationServiceError("ADAPTER_NOT_FOUND", `Unknown integration adapter "${integration.adapter}".`);
+  return adapter;
+}
+async function buildContextWithSecrets(dir, integration, env) {
+  const resolver = secretResolver(dir, env);
+  const { credentials, missing } = await resolveAllCredentials(integration, resolver, 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);
+  }
+}
+function validateId(id) {
+  if (!id || !id.trim()) throw new IntegrationServiceError("INTEGRATION_INVALID_INPUT", "Integration id is required.");
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(id)) throw new IntegrationServiceError("INTEGRATION_INVALID_INPUT", "Integration id must be alphanumeric with dashes, dots or underscores.");
+  if (id.length > 64) throw new IntegrationServiceError("INTEGRATION_INVALID_INPUT", "Integration id must be 64 characters or fewer.");
+}
+function createIntegration(dir, input) {
+  validateId(input.id);
+  if (!input.adapter || !input.adapter.trim()) throw new IntegrationServiceError("INTEGRATION_INVALID_INPUT", "An adapter type is required.");
+  const { integrations } = loadIntegrations(dir);
+  if (integrations.find((i) => i.id === input.id)) {
+    throw new IntegrationServiceError("INTEGRATION_ALREADY_EXISTS", `An integration with id "${input.id}" already exists.`);
+  }
+  const newConfig = integrationConfigFromInput(input);
+  integrations.push(newConfig);
+  saveIntegrations(dir, integrations);
+  return getIntegration(dir, input.id);
+}
+function updateIntegration(dir, id, input) {
+  const { integrations } = loadIntegrations(dir);
+  const idx = integrations.findIndex((i) => i.id === id);
+  if (idx < 0) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured.`);
+  const existing = integrations[idx];
+  if (input.enabled !== void 0) existing.enabled = input.enabled;
+  if (input.config !== void 0) existing.config = input.config;
+  if (input.secrets !== void 0) existing.secrets = input.secrets;
+  if (input.timeoutMs !== void 0) existing.timeoutMs = input.timeoutMs;
+  integrations[idx] = existing;
+  saveIntegrations(dir, integrations);
+  return getIntegration(dir, id);
+}
+function deleteIntegration(dir, id) {
+  const { integrations } = loadIntegrations(dir);
+  const idx = integrations.findIndex((i) => i.id === id);
+  if (idx < 0) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured.`);
+  const removed = integrations[idx];
+  integrations.splice(idx, 1);
+  saveIntegrations(dir, integrations);
+  const sp = secretProvider(dir);
+  for (const ref of Object.values(removed.secrets)) {
+    sp.delete(ref).catch(() => {
+    });
+  }
+}
+function enableIntegration(dir, id) {
+  return updateIntegration(dir, id, { enabled: true });
+}
+function disableIntegration(dir, id) {
+  return updateIntegration(dir, id, { enabled: false });
+}
+async function setIntegrationSecret(dir, id, secretName, value) {
+  const { integration } = requireIntegration(dir, id);
+  const refKey = secretRefKey(id, secretName);
+  const sp = secretProvider(dir);
+  await sp.set(refKey, value);
+  if (!integration.secrets[secretName] || integration.secrets[secretName] !== refKey) {
+    const { integrations } = loadIntegrations(dir);
+    const idx = integrations.findIndex((i) => i.id === id);
+    if (idx >= 0) {
+      integrations[idx].secrets[secretName] = refKey;
+      saveIntegrations(dir, integrations);
+    }
+  }
+}
+async function removeIntegrationSecret(dir, id, secretName) {
+  const { integration } = requireIntegration(dir, id);
+  const refKey = integration.secrets[secretName];
+  if (refKey) {
+    const sp = secretProvider(dir);
+    await sp.delete(refKey);
+  }
+  const { integrations } = loadIntegrations(dir);
+  const idx = integrations.findIndex((i) => i.id === id);
+  if (idx >= 0 && integrations[idx].secrets[secretName]) {
+    delete integrations[idx].secrets[secretName];
+    saveIntegrations(dir, integrations);
+  }
+}
+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 } = await buildContextWithSecrets(dir, 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 } = await buildContextWithSecrets(dir, 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 } = await buildContextWithSecrets(dir, 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,
@@ -9380,13 +10139,22 @@ export {
   buildRefinementHandoff,
   buildTopologyEnrichmentHandoff,
   computeRefinementStatus,
+  createIntegration,
   createWorkItem,
   cwd,
+  deleteIntegration,
+  disableIntegration,
   discoverKnowledge,
   discoverWorkItems,
+  enableIntegration,
   exists,
+  findLinkedWorkItem,
   findSystemPaths,
+  getAvailableIntegrationTypes,
+  getExternalWorkItem,
   getImpactCandidates,
+  getIntegration,
+  getIntegrationSecretStatus,
   getSystemMapProjection,
   getSystemNeighbors,
   getSystemNodeContext,
@@ -9395,21 +10163,30 @@ export {
   getWorkItemForEdit,
   getWorkItems,
   getWorkItemsSummary,
+  importExternalWorkItem,
+  integrationRegistry,
   isActiveState,
   isModule,
   join,
   knowledgeLayers,
   lifecycleCounts,
   lifecycleStateOf,
+  listExternalWorkItems,
+  listIntegrations,
   loadConfig,
   loadMappedModules,
   loadSystemTopology,
+  previewImport,
   readFile,
+  removeIntegrationSecret,
   searchSystemNodes,
+  setIntegrationSecret,
   topologyRevision,
   transitionWorkItem,
+  updateIntegration,
   updateWorkItem,
   validateSystemTopology,
   validateTopologyProposal,
-  validateWorkItem
+  validateWorkItem,
+  verifyIntegration
 };