@kolatts/pncli 5.0.1 → 5.1.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  assertValidCustomFields,
   getGlobalConfigPath,
   loadConfig,
   loadJsonFile,
@@ -9,13 +10,13 @@ import {
   setRepoConfigValue,
   writeGlobalConfig,
   writeRepoConfig
-} from "./chunk-3JICA4FZ.js";
+} from "./chunk-QHJ2HM5J.js";
 import {
-  createHttpClient
-} from "./chunk-VCECVN3F.js";
+  createHttpClient,
+  validateAlationAccessToken
+} from "./chunk-FAMJPKO4.js";
 import {
   ExitCode,
-  PncliError,
   fail,
   log,
   setGlobalOptions,
@@ -23,7 +24,10 @@ import {
   success,
   warn,
   writeRawOutput
-} from "./chunk-BHZORLOF.js";
+} from "./chunk-BOFSNQQ2.js";
+import {
+  PncliError
+} from "./chunk-HRNOAQDN.js";
 import {
   AdoCoreClient
 } from "./chunk-VDL32PSG.js";
@@ -604,7 +608,7 @@ var BitbucketClient = class {
               project: { key: opts.project }
             }
           },
-          reviewers: (opts.reviewers ?? []).map((slug) => ({ user: { slug } }))
+          reviewers: (opts.reviewers ?? []).map((name) => ({ user: { name } }))
         }
       }
     );
@@ -613,7 +617,7 @@ var BitbucketClient = class {
     const body = { version: opts.version };
     if (opts.title) body.title = opts.title;
     if (opts.description !== void 0) body.description = opts.description;
-    if (opts.reviewers) body.reviewers = opts.reviewers.map((slug) => ({ user: { slug } }));
+    if (opts.reviewers) body.reviewers = opts.reviewers.map((name) => ({ user: { name } }));
     return this.http.bitbucket(
       `${API}/projects/${opts.project}/repos/${opts.repo}/pull-requests/${opts.id}`,
       { method: "PUT", body }
@@ -1228,6 +1232,7 @@ function collectMetaFields(projects, issueType) {
 function buildFieldMap(fields) {
   const byName = /* @__PURE__ */ new Map();
   const byId = /* @__PURE__ */ new Map();
+  assertValidCustomFields(fields);
   for (const f of fields) {
     byName.set(f.name.toLowerCase(), f);
     byId.set(f.id, f);
@@ -6488,6 +6493,20 @@ async function runCredentialChecks(cfg, http) {
       results.figma = categorize(err);
     }
   }
+  if (!cfg.alation.refreshToken) {
+    results.alation = { status: "blank", message: "not configured" };
+  } else if (!cfg.alation.baseUrl) {
+    results.alation = { status: "error", message: "baseUrl not configured" };
+  } else if (cfg.alation.userId === void 0 || cfg.alation.userId === "") {
+    results.alation = { status: "error", message: "userId not configured" };
+  } else {
+    try {
+      await validateAlationAccessToken(cfg);
+      results.alation = { status: "valid", message: "ok" };
+    } catch (err) {
+      results.alation = categorize(err);
+    }
+  }
   return results;
 }
 
@@ -6553,6 +6572,47 @@ function marketplaceLabel(m) {
 function scrubToken(msg) {
   return msg.replace(/x-(?:token-auth|access-token):[^@]+@/g, "x-token-auth:***@");
 }
+function isConfiguredGitHubHost(repoUrl, githubBaseUrl) {
+  try {
+    const host = new URL(repoUrl).hostname;
+    if (host === "github.com") return true;
+    if (!githubBaseUrl) return false;
+    return new URL(githubBaseUrl).hostname === host;
+  } catch {
+    return false;
+  }
+}
+function resolveMarketplaceToken(explicitToken, repoUrl) {
+  if (explicitToken) return explicitToken;
+  if (!repoUrl) return void 0;
+  const resolved = loadConfig();
+  if (!isConfiguredGitHubHost(repoUrl, resolved.github.baseUrl)) return void 0;
+  return resolved.github.token;
+}
+var GIT_AUTH_FAILURE_PATTERNS = [
+  /invalid username or (password|token)/i,
+  /authentication failed/i,
+  /could not read username/i,
+  /could not read password/i,
+  /support for password authentication was removed/i
+];
+var GIT_NOT_FOUND_PATTERNS = [/repository not found/i];
+function describeGitFailure(rawMessage, marketplaceName, tokenSource) {
+  const msg = scrubToken(rawMessage);
+  if (GIT_AUTH_FAILURE_PATTERNS.some((p) => p.test(msg))) {
+    const hint = tokenSource === "explicit" ? `The token configured for marketplace "${marketplaceName}" was rejected \u2014 it may be expired, revoked, or missing required scopes. Update it with: pncli skills marketplace add <url> --token <new-token>` : tokenSource === "fallback" ? `The GitHub token pncli is using (PNCLI_GITHUB_TOKEN / GITHUB_TOKEN / github.token) was rejected for marketplace "${marketplaceName}" \u2014 it may be expired, revoked, or missing required scopes for this repo. Rotate that token, or set one specifically for this marketplace: pncli skills marketplace add <url> --token <new-token>` : `Marketplace "${marketplaceName}" requires authentication but no token is configured. Add one with: pncli skills marketplace add <url> --token <token>`;
+    return new Error(`${hint}
+
+Git reported: ${msg}`);
+  }
+  if (GIT_NOT_FOUND_PATTERNS.some((p) => p.test(msg))) {
+    const hint = tokenSource === "explicit" ? `Repository for marketplace "${marketplaceName}" was not found \u2014 check the URL and that the configured token has access to it.` : tokenSource === "fallback" ? `Repository for marketplace "${marketplaceName}" was not found \u2014 check the URL and that pncli's configured GitHub token has access to it.` : `Repository for marketplace "${marketplaceName}" was not found \u2014 if it's private, add a token: pncli skills marketplace add <url> --token <token>`;
+    return new Error(`${hint}
+
+Git reported: ${msg}`);
+  }
+  return new Error(msg);
+}
 function assertInteractive(hint) {
   if (!process.stdin.isTTY) {
     throw new Error(`This selection requires an interactive terminal. ${hint}`);
@@ -7019,7 +7079,7 @@ function upsertMarketplace(all, entry) {
     all.push(entry);
   }
 }
-function cloneOrReuseMarketplace(url, resolvedPath, opts) {
+function cloneOrReuseMarketplace(url, resolvedPath, opts, marketplaceName) {
   const hasGit = fs2.existsSync(path7.join(resolvedPath, ".git"));
   if (fs2.existsSync(resolvedPath) && !hasGit && fs2.readdirSync(resolvedPath).length > 0) {
     throw new Error(`Directory already exists and is not a git repo: ${resolvedPath}`);
@@ -7028,9 +7088,10 @@ function cloneOrReuseMarketplace(url, resolvedPath, opts) {
     warn(`Directory already contains a git repo at ${resolvedPath} \u2014 skipping clone, updating config and re-installing plugins.`);
     return;
   }
+  const resolvedToken = resolveMarketplaceToken(opts.token, url);
   const branchLabel = opts.branch ?? "remote default";
   warn(`Cloning ${url} (branch: ${branchLabel}) \u2192 ${resolvedPath}...`);
-  const cloneUrl = opts.token ? injectTokenIntoUrl(url, opts.token) : url;
+  const cloneUrl = resolvedToken ? injectTokenIntoUrl(url, resolvedToken) : url;
   const cloneArgs = ["clone"];
   if (opts.branch) cloneArgs.push("--branch", opts.branch);
   cloneArgs.push(cloneUrl, resolvedPath);
@@ -7045,15 +7106,17 @@ function cloneOrReuseMarketplace(url, resolvedPath, opts) {
     }
     if (!cloneActuallySucceeded) {
       const msg = e instanceof Error ? e.message : String(e);
-      throw new Error(scrubToken(msg));
+      const tokenSource = opts.token ? "explicit" : resolvedToken ? "fallback" : "none";
+      throw describeGitFailure(msg, marketplaceName, tokenSource);
     }
   }
 }
 function pullMarketplace(marketplacePath, repoUrl, token, marketplaceName) {
+  const resolvedToken = resolveMarketplaceToken(token, repoUrl);
   warn(`Pulling latest content for "${marketplaceName}"...`);
   const gitArgs = ["-C", marketplacePath];
-  if (repoUrl && token) {
-    gitArgs.push("-c", `remote.origin.url=${injectTokenIntoUrl(repoUrl, token)}`);
+  if (repoUrl && resolvedToken) {
+    gitArgs.push("-c", `remote.origin.url=${injectTokenIntoUrl(repoUrl, resolvedToken)}`);
   }
   gitArgs.push("pull");
   let pullOutput;
@@ -7061,7 +7124,8 @@ function pullMarketplace(marketplacePath, repoUrl, token, marketplaceName) {
     pullOutput = execFileSync3("git", gitArgs, { encoding: "utf8", stdio: ["inherit", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" } });
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    throw new Error(scrubToken(msg));
+    const tokenSource = token ? "explicit" : resolvedToken ? "fallback" : "none";
+    throw describeGitFailure(msg, marketplaceName, tokenSource);
   }
   const updated = !pullOutput.includes("Already up to date");
   if (pullOutput.trim() && updated) warn(pullOutput.trim());
@@ -7152,7 +7216,7 @@ function syncMarketplacePlugins(m, targetDir, force, pluginFilter, installedOnly
 function performMarketplaceAdd(url, localPath, opts) {
   const resolvedPath = path7.resolve(localPath ?? defaultMarketplacePath(url));
   const marketplaceName = opts.name ?? repoNameFromUrl(url);
-  cloneOrReuseMarketplace(url, resolvedPath, opts);
+  cloneOrReuseMarketplace(url, resolvedPath, opts, marketplaceName);
   const configPath = getGlobalConfigPath();
   const { existing, all } = loadMarketplacesConfig(configPath);
   const entry = {
@@ -8307,6 +8371,16 @@ function registerConfigCommands(program2) {
       } else {
         results.figma = { ok: null, message: "not configured" };
       }
+      if (cfg.alation.baseUrl && cfg.alation.refreshToken && cfg.alation.userId !== void 0 && cfg.alation.userId !== "") {
+        try {
+          await validateAlationAccessToken(cfg);
+          results.alation = { ok: true, message: "connected" };
+        } catch (err) {
+          results.alation = { ok: false, message: err instanceof Error ? err.message : String(err) };
+        }
+      } else {
+        results.alation = { ok: null, message: "not configured" };
+      }
       success(results, "config", "test", start);
     } catch (err) {
       fail(err, "config", "test", start);
@@ -8348,7 +8422,8 @@ function registerConfigCommands(program2) {
         ...dynamicEnvKeys,
         "logscale",
         "splitio",
-        "figma"
+        "figma",
+        "alation"
       ];
       if (cmdOpts.output === "table") {
         const labelWidth = Math.max(14, ...allServices.map((s) => s.length + 2));
@@ -8964,6 +9039,47 @@ async function initGlobalConfig(start) {
       }
     }
   }
+  process.stderr.write("\n\u2500\u2500 Alation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+  const useAlation = await confirm({
+    message: "Configure Alation for data catalog and Document Hub access?",
+    default: false
+  });
+  let alationBaseUrl = "";
+  let alationRefreshToken = "";
+  let alationUserId = "";
+  if (useAlation) {
+    process.stderr.write("  Generate a refresh token in Alation under your profile \u2192 Settings \u2192 Authentication \u2192 Create Refresh Token.\n");
+    process.stderr.write("  Note the numeric user ID shown with it; pncli exchanges the refresh token for short-lived API tokens itself.\n");
+    alationBaseUrl = await input2({
+      message: "Alation base URL (e.g. https://alation.imagile.dev):",
+      validate: (v) => v.trim().length > 0 || "Required"
+    });
+    alationRefreshToken = await password({
+      message: "Alation refresh token:"
+    });
+    alationUserId = await input2({
+      message: "Alation user ID (numeric):",
+      validate: (v) => /^\d+$/.test(v.trim()) || "Must be a positive integer"
+    });
+    if (alationBaseUrl && alationRefreshToken && alationUserId) {
+      process.stderr.write("\n  Verifying connection...\n");
+      try {
+        const tempConfig = {
+          ...loadConfig(),
+          alation: {
+            baseUrl: normalizeBaseUrl(alationBaseUrl),
+            refreshToken: alationRefreshToken,
+            userId: alationUserId.trim()
+          }
+        };
+        await validateAlationAccessToken(tempConfig);
+        process.stderr.write("  Connected.\n");
+      } catch (err) {
+        warn(`Could not connect to Alation: ${err instanceof Error ? err.message : String(err)}`);
+        warn("Config will be saved anyway. Check your URL, refresh token, and user ID and re-run pncli config init or pncli config test.");
+      }
+    }
+  }
   process.stderr.write("\n\u2500\u2500 Defaults \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
   const jiraProject = await input2({
     message: "Default Jira project key (optional):",
@@ -9121,6 +9237,13 @@ async function initGlobalConfig(start) {
         token: figmaToken
       }
     } : {},
+    ...useAlation && alationBaseUrl ? {
+      alation: {
+        baseUrl: normalizeBaseUrl(alationBaseUrl),
+        refreshToken: alationRefreshToken || void 0,
+        userId: alationUserId.trim() || void 0
+      }
+    } : {},
     defaults: {
       jira: {
         project: jiraProject || void 0
@@ -10009,10 +10132,10 @@ function registerAdoWorkCommands(ado) {
       const types = await discoverTypes(workClient, collection, project);
       if (opts.save) {
         const globalConfigPath = getGlobalConfigPath(globalOpts.config);
-        const fs7 = await import("fs");
-        const existing = JSON.parse(fs7.readFileSync(globalConfigPath, "utf8") || "{}");
+        const fs8 = await import("fs");
+        const existing = JSON.parse(fs8.readFileSync(globalConfigPath, "utf8") || "{}");
         existing.ado = { ...existing.ado ?? {}, discoveredTypes: types };
-        fs7.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+        fs8.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
         warn(`Saved ${types.length} types to ${globalConfigPath}`);
       }
       success(types, "ado", "work-types", start);
@@ -10041,11 +10164,11 @@ function registerAdoWorkCommands(ado) {
       ) : allFields;
       if (opts.save) {
         const globalConfigPath = getGlobalConfigPath(globalOpts.config);
-        const fs7 = await import("fs");
-        const existing = JSON.parse(fs7.readFileSync(globalConfigPath, "utf8") || "{}");
+        const fs8 = await import("fs");
+        const existing = JSON.parse(fs8.readFileSync(globalConfigPath, "utf8") || "{}");
         const aliases = buildDefaultAliases(allFields);
         existing.ado = { ...existing.ado ?? {}, discoveredFields: allFields, fieldAliases: aliases };
-        fs7.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+        fs8.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
         warn(`Saved ${allFields.length} fields and ${Object.keys(aliases).length} aliases to ${globalConfigPath}`);
       }
       success(fields, "ado", "work-fields", start);
@@ -10342,11 +10465,11 @@ function registerAdoRepoCommands(ado) {
       const start = Date.now();
       try {
         const globalOpts = ado.optsWithGlobals();
-        const { loadConfig: lc } = await import("./config-7FK4MAQC.js");
+        const { loadConfig: lc } = await import("./config-Y6IE6GY7.js");
         const config = lc({ configPath: globalOpts.config });
         const { collection, project, repo: repo2, gitClient } = getAdoContext(ado, true);
         const { AdoCoreClient: AdoCoreClient2 } = await import("./core-SWYVXOQ4.js");
-        const { createHttpClient: createHttpClient2 } = await import("./http-73CNKAH6.js");
+        const { createHttpClient: createHttpClient2 } = await import("./http-TAINU2LF.js");
         const http = createHttpClient2(config, Boolean(globalOpts.dryRun));
         const coreClient = new AdoCoreClient2(http);
         const me = await coreClient.getConnectionData(collection);
@@ -12345,6 +12468,35 @@ Expected format: https://www.figma.com/design/<file-key>/...`);
   }
   return input3;
 }
+var NODE_ID_PATTERN = /^[A-Za-z0-9]+:[A-Za-z0-9]+(?:;[A-Za-z0-9]+:[A-Za-z0-9]+)*$/;
+var NODE_ID_HINT = "Expected a node ID like 12:34 or 12-34, or a Figma URL with a node-id query param";
+function isUrl(input3) {
+  return input3.startsWith("http://") || input3.startsWith("https://");
+}
+function parseNodeId(input3) {
+  let raw = input3;
+  if (isUrl(input3)) {
+    try {
+      raw = new URL(input3).searchParams.get("node-id");
+    } catch {
+      raw = null;
+    }
+    if (raw === null) {
+      throw new Error(`Could not extract a Figma node ID from URL: ${input3}
+${NODE_ID_HINT}`);
+    }
+  }
+  const nodeId = raw.trim().replace(/-/g, ":");
+  if (!NODE_ID_PATTERN.test(nodeId)) {
+    throw new Error(`Invalid Figma node ID: ${input3}
+${NODE_ID_HINT}`);
+  }
+  return nodeId;
+}
+function findNodeIdInUrl(url) {
+  if (!new URL(url).searchParams.has("node-id")) return void 0;
+  return parseNodeId(url);
+}
 function getHttp5(program2) {
   const opts = program2.optsWithGlobals();
   return createHttpClient(
@@ -12354,11 +12506,38 @@ function getHttp5(program2) {
 }
 function registerFigmaCommands(program2) {
   const figma = program2.command("figma").description("Figma design operations (files, comments, versions)");
-  figma.command("file").description("Get a Figma file \u2014 metadata, structure, and component/style inventory").argument("<file-key-or-url>", "Figma file key or full Figma URL (https://www.figma.com/design/<key>/...)").option("--document", "Include the full document node tree (can be large; omitted by default)").action(async (fileKeyOrUrl, opts) => {
+  figma.command("file").description("Get a Figma file \u2014 metadata, structure, and component/style inventory (or a single node with --node-id)").argument("<file-key-or-url>", "Figma file key or full Figma URL (https://www.figma.com/design/<key>/...); a node-id query param is auto-detected").option("--document", "Include the full document node tree (can be large; omitted by default)").option("--node-id <id>", "Fetch only this node and its descendants instead of the whole file (overrides any node-id detected in the URL)").action(async (fileKeyOrUrl, opts) => {
     const start = Date.now();
-    const { success: success2, fail: fail2 } = await import("./output-3G3WZVZA.js");
+    const { success: success2, fail: fail2 } = await import("./output-HDUIIXUI.js");
     try {
       const fileKey = parseFileKey(fileKeyOrUrl);
+      const nodeId = opts.nodeId ? parseNodeId(opts.nodeId) : isUrl(fileKeyOrUrl) ? findNodeIdInUrl(fileKeyOrUrl) : void 0;
+      if (nodeId) {
+        const data2 = await getHttp5(program2).figma(
+          `/v1/files/${encodeURIComponent(fileKey)}/nodes`,
+          { params: { ids: nodeId } }
+        );
+        const node = data2.nodes[nodeId];
+        if (!node) {
+          throw new Error(`Node ${nodeId} not found in file ${fileKey}`);
+        }
+        success2(
+          {
+            fileKey,
+            nodeId,
+            name: data2.name,
+            lastModified: data2.lastModified,
+            thumbnailUrl: data2.thumbnailUrl,
+            document: node.document,
+            componentCount: node.components ? Object.keys(node.components).length : 0,
+            styleCount: node.styles ? Object.keys(node.styles).length : 0
+          },
+          "figma",
+          "file",
+          start
+        );
+        return;
+      }
       const params = {};
       if (!opts.document) {
         params["depth"] = 1;
@@ -12388,7 +12567,7 @@ function registerFigmaCommands(program2) {
   });
   figma.command("comments").description("Get comments on a Figma file").argument("<file-key-or-url>", "Figma file key or full Figma URL").option("--as-of <date>", "ISO 8601 timestamp \u2014 return only comments created before this time").action(async (fileKeyOrUrl, opts) => {
     const start = Date.now();
-    const { success: success2, fail: fail2 } = await import("./output-3G3WZVZA.js");
+    const { success: success2, fail: fail2 } = await import("./output-HDUIIXUI.js");
     try {
       const fileKey = parseFileKey(fileKeyOrUrl);
       const params = {};
@@ -12406,7 +12585,7 @@ function registerFigmaCommands(program2) {
   });
   figma.command("versions").description("Get the version history of a Figma file").argument("<file-key-or-url>", "Figma file key or full Figma URL").action(async (fileKeyOrUrl) => {
     const start = Date.now();
-    const { success: success2, fail: fail2 } = await import("./output-3G3WZVZA.js");
+    const { success: success2, fail: fail2 } = await import("./output-HDUIIXUI.js");
     try {
       const fileKey = parseFileKey(fileKeyOrUrl);
       const data = await getHttp5(program2).figma(`/v1/files/${encodeURIComponent(fileKey)}/versions`);
@@ -12422,7 +12601,7 @@ function registerFigmaCommands(program2) {
   });
   figma.command("project-files").description("List files in a Figma project").argument("<project-id>", "Figma project ID (visible in the project URL)").action(async (projectId) => {
     const start = Date.now();
-    const { success: success2, fail: fail2 } = await import("./output-3G3WZVZA.js");
+    const { success: success2, fail: fail2 } = await import("./output-HDUIIXUI.js");
     try {
       const data = await getHttp5(program2).figma(`/v1/projects/${encodeURIComponent(projectId)}/files`);
       success2(
@@ -12437,7 +12616,7 @@ function registerFigmaCommands(program2) {
   });
   figma.command("me").description("Get the current Figma user (useful for verifying credentials)").action(async () => {
     const start = Date.now();
-    const { success: success2, fail: fail2 } = await import("./output-3G3WZVZA.js");
+    const { success: success2, fail: fail2 } = await import("./output-HDUIIXUI.js");
     try {
       const data = await getHttp5(program2).figma("/v1/me");
       success2(data, "figma", "me", start);
@@ -12447,6 +12626,410 @@ function registerFigmaCommands(program2) {
   });
 }
 
+// src/services/alation/commands.ts
+import fs7 from "fs";
+var MAX_PAGE = 1e3;
+function parseIntOption(value, flag) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new PncliError(`Invalid ${flag} "${value}". Expected a non-negative integer.`, 1);
+  }
+  return Number(trimmed);
+}
+function parsePositiveId(value, what) {
+  const trimmed = value.trim();
+  if (!/^[1-9]\d*$/.test(trimmed)) {
+    throw new PncliError(`Invalid ${what} "${value}". Expected a positive integer ID.`, 1);
+  }
+  return Number(trimmed);
+}
+function pageParams(opts) {
+  const limit = parseIntOption(opts.limit, "--limit") ?? 100;
+  const skip = parseIntOption(opts.skip, "--skip") ?? 0;
+  if (limit < 1 || limit > MAX_PAGE) {
+    throw new PncliError(`--limit must be between 1 and ${MAX_PAGE} (Alation's per-request cap).`, 1);
+  }
+  return { limit, skip };
+}
+var SEARCH_OTYPES = [
+  "api_resource",
+  "api_resource_field",
+  "api_resource_folder",
+  "article",
+  "bi_field",
+  "catalog_set",
+  "column",
+  "dataflow",
+  "datasource",
+  "doc_schema",
+  "docstore_collection",
+  "docstore_folder",
+  "domain",
+  "execution_result",
+  "file",
+  "filesystem",
+  "function",
+  "glossary",
+  "glossary_term",
+  "glossary_v3",
+  "group",
+  "query_or_statement",
+  "report_collection",
+  "report_datasource",
+  "report_object",
+  "report_source",
+  "schema",
+  "table",
+  "tag",
+  "thread",
+  "user",
+  "value"
+];
+function parseOtypes(raw) {
+  if (raw === void 0) return void 0;
+  const otypes = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  if (otypes.length === 0) throw new PncliError("--otype cannot be empty", 1);
+  const bad = otypes.filter((o) => !SEARCH_OTYPES.includes(o));
+  if (bad.length) {
+    throw new PncliError(`Unknown --otype value(s): ${bad.join(", ")}. Valid: ${SEARCH_OTYPES.join(", ")}`, 1);
+  }
+  return otypes;
+}
+function toCustomFields(fields) {
+  if (fields === void 0) return [];
+  if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
+    throw new PncliError('--input-file "fields" must be an object keyed by Alation custom field ID', 1);
+  }
+  return Object.entries(fields).map(([key, value]) => {
+    if (!/^\d+$/.test(key)) {
+      throw new PncliError(`--input-file "fields" key "${key}" is not a numeric Alation field_id`, 1);
+    }
+    return { field_id: Number(key), value: resolveAtFileRef(value) };
+  });
+}
+var ALATION_DOCUMENT_INPUT_FILE_SCHEMA = {
+  type: "object",
+  properties: {
+    title: { type: "string", description: "Document title" },
+    description: { type: "string", description: 'Document summary; "@path" reads the value from a file' },
+    hub: { type: "integer", description: "document_hub_id (required on create)" },
+    folder: { type: "integer", description: "parent_folder_id (required on create)" },
+    template: { type: "integer", description: "template_id; required whenever fields are supplied" },
+    parentDocument: { type: "integer", description: "parent_document_id for a sub-document" },
+    navLinkFolders: { type: "array", items: { type: "integer" }, description: "nav_link_folder_ids" },
+    fields: {
+      type: "object",
+      description: 'Custom field values keyed by numeric Alation field_id; string values starting with "@" are read from that file',
+      additionalProperties: true
+    }
+  }
+};
+var ALATION_DOCUMENT_INPUT_FILE_EXAMPLE = {
+  title: "Customer table onboarding notes",
+  description: "@docs/customer-notes.md",
+  hub: 1,
+  folder: 42,
+  template: 7,
+  fields: { "10001": "Team Data Platform" }
+};
+function getHttp6(program2) {
+  const opts = program2.optsWithGlobals();
+  return createHttpClient(
+    loadConfig({ configPath: opts.config }),
+    Boolean(opts.dryRun)
+  );
+}
+async function getOne(http, path10, id, what) {
+  const rows = await http.alation(path10, { params: { id, limit: 1 } });
+  const row = Array.isArray(rows) ? rows.find((r) => r.id === id) ?? rows[0] : void 0;
+  if (!row) throw new PncliError(`${what} ${id} not found`, 404);
+  return row;
+}
+function buildDocumentPayload(opts) {
+  const fromJson = {};
+  if (opts.inputFile) {
+    const parsed = readJsonInputFile(opts.inputFile);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new PncliError("--input-file must contain a JSON object. Run: pncli alation document schema", 1);
+    }
+    Object.assign(fromJson, parsed);
+  }
+  const fromFlags = {
+    title: opts.title,
+    description: opts.description,
+    hub: opts.hub !== void 0 ? parsePositiveId(opts.hub, "--hub") : void 0,
+    folder: opts.folder !== void 0 ? parsePositiveId(opts.folder, "--folder") : void 0,
+    template: opts.template !== void 0 ? parsePositiveId(opts.template, "--template") : void 0,
+    parentDocument: opts.parentDocument !== void 0 ? parsePositiveId(opts.parentDocument, "--parent-document") : void 0
+  };
+  const { merged, overrides } = mergeWithOverrides(fromJson, fromFlags);
+  if (overrides.length) warn(`--input-file values overridden by flags: ${overrides.join(", ")}`);
+  const payload = {};
+  if (merged.title !== void 0) payload.title = merged.title;
+  if (merged.description !== void 0) payload.description = resolveAtFileRef(merged.description);
+  if (merged.hub !== void 0) payload.document_hub_id = merged.hub;
+  if (merged.folder !== void 0) payload.parent_folder_id = merged.folder;
+  if (merged.template !== void 0) payload.template_id = merged.template;
+  if (merged.parentDocument !== void 0) payload.parent_document_id = merged.parentDocument;
+  if (merged.navLinkFolders !== void 0) payload.nav_link_folder_ids = merged.navLinkFolders;
+  const customFields = toCustomFields(merged.fields);
+  if (customFields.length) {
+    if (payload.template_id === void 0) {
+      throw new PncliError('Alation requires template_id whenever custom fields are set. Pass --template <id> or "template" in --input-file.', 1);
+    }
+    payload.custom_fields = customFields;
+  }
+  return { payload, overrides };
+}
+function registerAlationCommands(program2) {
+  const alation = program2.command("alation").description("Alation data catalog (data sources, schemas, tables, columns, search, documents)");
+  const token = alation.command("token").description("API access token operations");
+  token.command("status").description("Mint an API access token from the configured refresh token and report its expiry (verifies credentials)").action(async () => {
+    const start = Date.now();
+    try {
+      const opts = program2.optsWithGlobals();
+      const config = loadConfig({ configPath: opts.config });
+      if (opts.dryRun) {
+        fs7.writeSync(process.stderr.fd, `DRY RUN: POST ${config.alation.baseUrl ?? "<alation.baseUrl>"}/integration/v1/createAPIAccessToken/ (token exchange skipped)
+`);
+        process.exitCode = ExitCode.SUCCESS;
+        throw new PncliError("dry-run", 0);
+      }
+      const data = await validateAlationAccessToken(config);
+      success(data, "alation", "token-status", start);
+    } catch (err) {
+      fail(err, "alation", "token-status", start);
+    }
+  });
+  const datasource = alation.command("datasource").description("Data source operations");
+  datasource.command("list").description("List data sources").option("--include-undeployed", "Include data sources whose setup is incomplete").option("--include-hidden", "Include hidden data sources").action(async (opts) => {
+    const start = Date.now();
+    try {
+      const params = {};
+      if (opts.includeUndeployed) params.include_undeployed = true;
+      if (opts.includeHidden) params.include_hidden = true;
+      const data = await getHttp6(program2).alation("integration/v1/datasource/", { params });
+      success({ count: data.length, datasources: data }, "alation", "datasource-list", start);
+    } catch (err) {
+      fail(err, "alation", "datasource-list", start);
+    }
+  });
+  datasource.command("get").description("Get a data source by ID").argument("<id>", "Data source ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const dsId = parsePositiveId(id, "data source ID");
+      const data = await getHttp6(program2).alation(`integration/v1/datasource/${dsId}/`);
+      success(data, "alation", "datasource-get", start);
+    } catch (err) {
+      fail(err, "alation", "datasource-get", start);
+    }
+  });
+  const schema = alation.command("schema").description("Schema operations");
+  schema.command("list").description("List schemas, optionally within one data source").option("--ds <id>", "Filter by data source ID").option("--name <name>", "Filter by exact schema name").option("--limit <n>", "Page size (max 1000)", "100").option("--skip <n>", "Number of results to skip", "0").action(async (opts) => {
+    const start = Date.now();
+    try {
+      const params = { ...pageParams(opts) };
+      if (opts.ds) params.ds_id = parsePositiveId(opts.ds, "--ds");
+      if (opts.name) params.name = opts.name;
+      const data = await getHttp6(program2).alation("integration/v2/schema/", { params });
+      success({ count: data.length, limit: params.limit, skip: params.skip, schemas: data }, "alation", "schema-list", start);
+    } catch (err) {
+      fail(err, "alation", "schema-list", start);
+    }
+  });
+  schema.command("get").description("Get a schema by ID").argument("<id>", "Schema ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const data = await getOne(getHttp6(program2), "integration/v2/schema/", parsePositiveId(id, "schema ID"), "Schema");
+      success(data, "alation", "schema-get", start);
+    } catch (err) {
+      fail(err, "alation", "schema-get", start);
+    }
+  });
+  const table = alation.command("table").description("Table operations");
+  table.command("list").description("List tables (descriptions, custom fields, fully-qualified keys)").option("--ds <id>", "Filter by data source ID").option("--schema <id>", "Filter by schema ID").option("--schema-name <name>", "Filter by schema name").option("--name <name>", "Filter by exact table name").option("--search <text>", "Case-insensitive substring match on table name").option("--limit <n>", "Page size (max 1000)", "100").option("--skip <n>", "Number of results to skip", "0").action(async (opts) => {
+    const start = Date.now();
+    try {
+      const params = { ...pageParams(opts) };
+      if (opts.ds) params.ds_id = parsePositiveId(opts.ds, "--ds");
+      if (opts.schema) params.schema_id = parsePositiveId(opts.schema, "--schema");
+      if (opts.schemaName) params.schema_name = opts.schemaName;
+      if (opts.name) params.name = opts.name;
+      if (opts.search) params.name__icontains = opts.search;
+      const data = await getHttp6(program2).alation("integration/v2/table/", { params });
+      success({ count: data.length, limit: params.limit, skip: params.skip, tables: data }, "alation", "table-list", start);
+    } catch (err) {
+      fail(err, "alation", "table-list", start);
+    }
+  });
+  table.command("get").description("Get a table by ID, optionally with its columns").argument("<id>", "Table ID").option("--columns", "Also fetch the table's columns (up to 1000)").action(async (id, opts) => {
+    const start = Date.now();
+    try {
+      const http = getHttp6(program2);
+      const tableId = parsePositiveId(id, "table ID");
+      const data = await getOne(http, "integration/v2/table/", tableId, "Table");
+      if (opts.columns) {
+        const columns = await http.alation("integration/v2/column/", {
+          params: { table_id: tableId, limit: MAX_PAGE, order_by: "id" }
+        });
+        success({ ...data, columnCount: columns.length, columns }, "alation", "table-get", start);
+        return;
+      }
+      success(data, "alation", "table-get", start);
+    } catch (err) {
+      fail(err, "alation", "table-get", start);
+    }
+  });
+  const column = alation.command("column").description("Column operations");
+  column.command("list").description("List columns of a table (types, descriptions, keys, custom fields)").option("--table <id>", "Filter by table ID").option("--table-name <name>", "Filter by table name").option("--schema <id>", "Filter by schema ID").option("--ds <id>", "Filter by data source ID").option("--name <name>", "Filter by exact column name").option("--search <text>", "Case-insensitive substring match on column name").option("--limit <n>", "Page size (max 1000)", "100").option("--skip <n>", "Number of results to skip", "0").action(async (opts) => {
+    const start = Date.now();
+    try {
+      if (!opts.table && !opts.tableName && !opts.schema && !opts.ds && !opts.name && !opts.search) {
+        throw new PncliError("Pass at least one filter (--table, --table-name, --schema, --ds, --name, or --search); listing every column in the catalog is not supported.", 1);
+      }
+      const params = { ...pageParams(opts) };
+      if (opts.table) params.table_id = parsePositiveId(opts.table, "--table");
+      if (opts.tableName) params.table_name = opts.tableName;
+      if (opts.schema) params.schema_id = parsePositiveId(opts.schema, "--schema");
+      if (opts.ds) params.ds_id = parsePositiveId(opts.ds, "--ds");
+      if (opts.name) params.name = opts.name;
+      if (opts.search) params.name__icontains = opts.search;
+      const data = await getHttp6(program2).alation("integration/v2/column/", { params });
+      success({ count: data.length, limit: params.limit, skip: params.skip, columns: data }, "alation", "column-list", start);
+    } catch (err) {
+      fail(err, "alation", "column-list", start);
+    }
+  });
+  column.command("get").description("Get a column by ID").argument("<id>", "Column ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const data = await getOne(getHttp6(program2), "integration/v2/column/", parsePositiveId(id, "column ID"), "Column");
+      success(data, "alation", "column-get", start);
+    } catch (err) {
+      fail(err, "alation", "column-get", start);
+    }
+  });
+  alation.command("search").description("Full-text search across the catalog").argument("<query>", "Search text").option("--otype <types>", `Comma-separated object types to restrict to (e.g. table,column). Valid: ${SEARCH_OTYPES.join(", ")}`).option("--limit <n>", "Maximum results (default 20, max 10000)", "20").option("--offset <n>", "Index of the first result", "0").action(async (query, opts) => {
+    const start = Date.now();
+    try {
+      const limit = parseIntOption(opts.limit, "--limit") ?? 20;
+      const offset = parseIntOption(opts.offset, "--offset") ?? 0;
+      if (limit > 1e4) throw new PncliError("--limit must be at most 10000", 1);
+      const params = { q: query, limit, offset };
+      const otypes = parseOtypes(opts.otype);
+      if (otypes) params.filters = JSON.stringify({ otypes });
+      const data = await getHttp6(program2).alation("integration/v1/search/", { params });
+      success(
+        { query, total: data.total, limit: data.limit, offset: data.offset, fullSearchUrl: data.full_search_url, results: data.results },
+        "alation",
+        "search",
+        start
+      );
+    } catch (err) {
+      fail(err, "alation", "search", start);
+    }
+  });
+  const folder = alation.command("folder").description("Document Hub folder operations");
+  folder.command("list").description("List folders in a Document Hub").option("--hub <id>", "Document hub ID").option("--parent <id>", "Parent folder ID (list its subfolders)").option("--search <text>", "Filter on textual fields").option("--limit <n>", "Page size (max 1000)", "100").option("--skip <n>", "Number of results to skip", "0").action(async (opts) => {
+    const start = Date.now();
+    try {
+      const params = { ...pageParams(opts) };
+      if (opts.hub) params.document_hub_id = parsePositiveId(opts.hub, "--hub");
+      if (opts.parent) params.parent_folder_id = parsePositiveId(opts.parent, "--parent");
+      if (opts.search) params.search = opts.search;
+      const data = await getHttp6(program2).alation("integration/v2/folder/", { params });
+      success({ count: data.length, limit: params.limit, skip: params.skip, folders: data }, "alation", "folder-list", start);
+    } catch (err) {
+      fail(err, "alation", "folder-list", start);
+    }
+  });
+  folder.command("get").description("Get a Document Hub folder by ID").argument("<id>", "Folder ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const data = await getOne(getHttp6(program2), "integration/v2/folder/", parsePositiveId(id, "folder ID"), "Folder");
+      success(data, "alation", "folder-get", start);
+    } catch (err) {
+      fail(err, "alation", "folder-get", start);
+    }
+  });
+  const document = alation.command("document").description("Document Hub document operations");
+  document.command("list").description("List documents in a Document Hub or folder").option("--hub <id>", "Document hub ID").option("--folder <id>", "Parent folder ID").option("--parent-document <id>", "Parent document ID (list sub-documents)").option("--search <text>", "Filter on all textual fields").option("--deleted", "Return only deleted documents").option("--limit <n>", "Page size (max 1000)", "100").option("--skip <n>", "Number of results to skip", "0").action(async (opts) => {
+    const start = Date.now();
+    try {
+      const params = { ...pageParams(opts) };
+      if (opts.hub) params.document_hub_id = parsePositiveId(opts.hub, "--hub");
+      if (opts.folder) params.parent_folder_id = parsePositiveId(opts.folder, "--folder");
+      if (opts.parentDocument) params.parent_document_id = parsePositiveId(opts.parentDocument, "--parent-document");
+      if (opts.search) params.search = opts.search;
+      if (opts.deleted) params.deleted = true;
+      const data = await getHttp6(program2).alation("integration/v2/document/", { params });
+      success({ count: data.length, limit: params.limit, skip: params.skip, documents: data }, "alation", "document-list", start);
+    } catch (err) {
+      fail(err, "alation", "document-list", start);
+    }
+  });
+  document.command("get").description("Get a document by ID, including its custom field values").argument("<id>", "Document ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const data = await getOne(getHttp6(program2), "integration/v2/document/", parsePositiveId(id, "document ID"), "Document");
+      success(data, "alation", "document-get", start);
+    } catch (err) {
+      fail(err, "alation", "document-get", start);
+    }
+  });
+  document.command("schema").description("Print the --input-file JSON schema and an example for document create/update").option("--example-only", "Print only the runnable example JSON (no envelope) \u2014 pipeable straight into --input-file").action((opts) => {
+    const start = Date.now();
+    if (opts.exampleOnly) {
+      writeRawOutput(JSON.stringify(ALATION_DOCUMENT_INPUT_FILE_EXAMPLE, null, 2) + "\n");
+      return;
+    }
+    success({ schema: ALATION_DOCUMENT_INPUT_FILE_SCHEMA, example: ALATION_DOCUMENT_INPUT_FILE_EXAMPLE }, "alation", "document-schema", start);
+  });
+  document.command("create").description("Create a document (async \u2014 returns a job ID; check it with `alation job get`)").option("--title <title>", "Document title").option("--description <text>", "Document summary").option("--hub <id>", "Document hub ID").option("--folder <id>", "Parent folder ID").option("--template <id>", "Template ID (required when custom fields are set)").option("--parent-document <id>", "Parent document ID for a sub-document").option("--input-file <path>", 'JSON file with title/description/hub/folder/template/fields (see `alation document schema`); "-" reads stdin').action(async (opts) => {
+    const start = Date.now();
+    try {
+      const { payload, overrides } = buildDocumentPayload(opts);
+      for (const [key, flag] of [["title", "--title"], ["document_hub_id", "--hub"], ["parent_folder_id", "--folder"]]) {
+        if (payload[key] === void 0) throw new PncliError(`${flag} is required to create a document (or set it in --input-file)`, 1);
+      }
+      const data = await getHttp6(program2).alation("integration/v2/document/", { method: "POST", body: [payload] });
+      success({ jobId: data.job_id, document: payload, ...overrides.length ? { overrides } : {} }, "alation", "document-create", start);
+    } catch (err) {
+      fail(err, "alation", "document-create", start);
+    }
+  });
+  document.command("update").description("Update a document (async \u2014 returns a job ID; custom field values replace existing values per field)").argument("<id>", "Document ID").option("--title <title>", "New title").option("--description <text>", "New summary").option("--folder <id>", "Move to this parent folder").option("--template <id>", "Template ID (required when custom fields are set)").option("--input-file <path>", 'JSON file with title/description/folder/template/fields (see `alation document schema`); "-" reads stdin').action(async (id, opts) => {
+    const start = Date.now();
+    try {
+      const documentId = parsePositiveId(id, "document ID");
+      const { payload, overrides } = buildDocumentPayload(opts);
+      if (payload.document_hub_id !== void 0) {
+        throw new PncliError('A document cannot change hubs; remove "hub" from --input-file.', 1);
+      }
+      if (Object.keys(payload).length === 0) {
+        throw new PncliError("Nothing to update. Pass --title, --description, --folder, or --input-file.", 1);
+      }
+      const body = [{ id: documentId, ...payload }];
+      const data = await getHttp6(program2).alation("integration/v2/document/", { method: "PUT", body });
+      success({ jobId: data.job_id, document: body[0], ...overrides.length ? { overrides } : {} }, "alation", "document-update", start);
+    } catch (err) {
+      fail(err, "alation", "document-update", start);
+    }
+  });
+  const job = alation.command("job").description("Background job operations");
+  job.command("get").description("Get the status of a bulk job (returned by document create/update)").argument("<id>", "Job ID").action(async (id) => {
+    const start = Date.now();
+    try {
+      const jobId = parsePositiveId(id, "job ID");
+      const data = await getHttp6(program2).alation("api/v1/bulk_metadata/job/", { params: { id: jobId } });
+      success({ jobId, ...data }, "alation", "job-get", start);
+    } catch (err) {
+      fail(err, "alation", "job-get", start);
+    }
+  });
+}
+
 // src/cli.ts
 if (!process.env.PNCLI_VERIFY_TLS) {
   process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
@@ -12492,6 +13075,7 @@ registerDynatraceCommands(program);
 registerLogscaleCommands(program);
 registerSplitioCommands(program);
 registerFigmaCommands(program);
+registerAlationCommands(program);
 program.addHelpText("after", `
 Services:
   git          Local git operations (status, diff, log, branch)
@@ -12513,6 +13097,7 @@ Services:
   logscale     LogScale (log query, repositories)
   splitio      Split.IO (feature flags, Change Requests)
   figma        Figma (files, comments, version history)
+  alation      Alation (data sources, schemas, tables, columns, search, Document Hubs)
   config       Manage pncli configuration
   doctor       Diagnose pncli setup (config files, credentials, agent skills)
   skills       Install and manage agent skills (Codex, GitHub Copilot, Claude Code)