@credibledata/cred-cli 0.0.102 → 0.0.103

package/src/commands/get.ts

@@ -3,13 +3,21 @@ import { Command } from "commander";
 import { controlPlanesByEnv, Environment } from "../constants";
 import { getGroup } from "./group/getgroup";
 import { getEnvironment } from "./environment/getenvironment";
+import { getMaterialization } from "./materialization/getmaterialization";
+import { getIndex } from "./materialization/getindex";
+import { getPreaggregate } from "./materialization/getpreaggregate";
+import { getRun } from "./materialization/getrun";
 import { warnProjectDeprecated } from "./legacy";
+import { getPermission } from "./permission/getpermission";
 
 export const registerGetCommands = (cli: Command, environment: Environment) => {
    const get = cli
       .command("get")
       .description("Get a resource")
-      .argument("<resource>", "The resource to get (environment | group)");
+      .argument(
+         "<resource>",
+         "The resource to get (environment | group | permission | materialization | index | preaggregate | run)",
+      );
 
    const getEnvironmentAction = (environmentName: string, options: any) => {
       getEnvironment(
@@ -41,4 +49,105 @@ export const registerGetCommands = (cli: Command, environment: Environment) => {
       .action((groupName, options) => {
          getGroup(controlPlanesByEnv[environment], groupName, options.debug);
       });
+
+   get.command("permission")
+      .description(
+         "Get a user or group's permission on the organization, an environment, or a package.",
+      )
+      .argument(
+         "<userGroupId>",
+         "Whose permission to get [user:{email}|group:{groupName}|user:*]",
+      )
+      .option(
+         "--environment <environmentName>",
+         "Get the permission on this environment instead of the organization.",
+      )
+      .option(
+         "--package <packageName>",
+         "Get the permission on this package. Uses --environment, or the current environment.",
+      )
+      .option("--debug")
+      .action((userGroupId, options) => {
+         getPermission(
+            controlPlanesByEnv[environment],
+            userGroupId,
+            options.debug || false,
+            { environment: options.environment, package: options.package },
+         );
+      });
+
+   get.command("materialization")
+      .alias("mat")
+      .description(
+         "Get a materialization anchor by id (status, physical table + connection, serving build, freshness, staleness).",
+      )
+      .argument("<packageName>", "The package that owns the materialization.")
+      .argument("<versionId>", "The version that binds it (e.g. 0.1.21).")
+      .argument("<materializationId>", "The materialization id.")
+      .option("--debug")
+      .action((packageName, versionId, materializationId, options) => {
+         getMaterialization(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            materializationId,
+            options.debug,
+         );
+      });
+
+   get.command("index")
+      .description(
+         "Get a dimensional index anchor by id (status, row count, lastIndexedAt, freshness, staleness).",
+      )
+      .argument("<packageName>", "The package that owns the index.")
+      .argument("<versionId>", "The version that binds it (e.g. 0.1.21).")
+      .argument("<indexId>", "The index (binding) id.")
+      .option("--debug")
+      .action((packageName, versionId, indexId, options) => {
+         getIndex(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            indexId,
+            options.debug,
+         );
+      });
+
+   get.command("preaggregate")
+      .alias("preagg")
+      .description(
+         "Get a pre-aggregated measure by id (status, grain, row count, lastBuiltAt, freshness, staleness).",
+      )
+      .argument("<packageName>", "The package that owns the pre-aggregation.")
+      .argument("<versionId>", "The version that binds it (e.g. 0.1.21).")
+      .argument(
+         "<preaggregateId>",
+         "The pre-aggregation id, as printed by `cred ls preaggregate`. It addresses a measure within a rollup — do not construct one by hand.",
+      )
+      .option("--debug")
+      .action((packageName, versionId, preaggregateId, options) => {
+         getPreaggregate(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            preaggregateId,
+            options.debug,
+         );
+      });
+
+   get.command("run")
+      .description(
+         "Get a run by id, including its build-plan graph (per-unit state, physical table names, row counts).",
+      )
+      .argument("<packageName>", "The package that owns the run.")
+      .argument("<runId>", "The run id.")
+      .option("--debug")
+      .action((packageName, runId, options) => {
+         getRun(
+            controlPlanesByEnv[environment],
+            packageName,
+            runId,
+            options.debug,
+         );
+      });
 };

package/src/commands/list.ts

@@ -8,7 +8,12 @@ import { listGroupAccessTokens } from "./groupaccesstoken/listTokens";
 import { printOutPackages } from "./package/listpackages";
 import { printOutEnvironments } from "./environment/listenvironments";
 import { listVersions } from "./version/listversions";
+import { listMaterializations } from "./materialization/listmaterializations";
+import { listIndexes } from "./materialization/listindexes";
+import { listPreaggregates } from "./materialization/listpreaggregates";
+import { listRuns } from "./materialization/listruns";
 import { warnProjectDeprecated } from "./legacy";
+import { listPermissions } from "./permission/listpermissions";
 
 export const registerListCommands = (
    cli: Command,
@@ -130,6 +135,172 @@ export const registerListCommands = (
          );
       });
 
+   list
+      .command("materialization")
+      .alias("materializations")
+      .description(
+         "List the materializations of a package version (status + failure reason).",
+      )
+      .argument(
+         "<packageName>",
+         "The name of the package whose materializations to list.",
+      )
+      .argument(
+         "<versionId>",
+         "The version that binds the materializations (e.g. 0.1.21).",
+      )
+      .option("--debug")
+      .action((packageName, versionId, options) => {
+         listMaterializations(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            options.debug,
+         );
+      });
+
+   list
+      .command("index")
+      .alias("indexes")
+      .description(
+         "List the dimensional search indexes of a package version (status + failure reason + freshness).",
+      )
+      .argument(
+         "<packageName>",
+         "The name of the package whose indexes to list.",
+      )
+      .argument(
+         "<versionId>",
+         "The version that binds the indexes (e.g. 0.1.21).",
+      )
+      .option("--debug")
+      // No static defaults: a Commander default of "-1" for --page-size would make it
+      // always-set, so parsePaginationParams takes its "return all records" branch and
+      // silently ignores a lone --page N. Leaving both unset (undefined) preserves the
+      // all-records default (neither flag → branch 1) while letting --page N default the
+      // page size to a finite page (utils.parsePaginationParams).
+      .option("--page <number>", `Page number (starts at ${DEFAULT_PAGE})`)
+      .option(
+         "--page-size <number>",
+         `Items per page (default: all records, max: 500)`,
+      )
+      .action((packageName, versionId, options) => {
+         listIndexes(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            options.debug,
+            options.page,
+            options.pageSize,
+         );
+      });
+
+   list
+      .command("preaggregate")
+      .alias("preaggregates")
+      .alias("preaggs")
+      .description(
+         "List the pre-aggregated measures of a package version (status + failure reason + grain + freshness). One entry per measure, so several may share a rollup table.",
+      )
+      .argument(
+         "<packageName>",
+         "The name of the package whose pre-aggregations to list.",
+      )
+      .argument(
+         "<versionId>",
+         "The version that binds the pre-aggregations (e.g. 0.1.21).",
+      )
+      .option("--debug")
+      .option(
+         "--source <sourceName>",
+         "Only list the pre-aggregated measures of this authored source.",
+      )
+      // No static defaults — see the note on `ls index` above.
+      .option("--page <number>", `Page number (starts at ${DEFAULT_PAGE})`)
+      .option(
+         "--page-size <number>",
+         `Items per page (default: all records, max: 500)`,
+      )
+      .action((packageName, versionId, options) => {
+         listPreaggregates(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            options.source,
+            options.debug,
+            options.page,
+            options.pageSize,
+         );
+      });
+
+   list
+      .command("run")
+      .alias("runs")
+      .description(
+         "List the build/refresh runs of a package (most recent first). Runs are package-scoped and span all three families (materialized sources, dimensional indexes and pre-aggregations); pass a version to filter to the runs it initiated, or --source/--dimension/--measure to filter to a targeted unit.",
+      )
+      .argument("<packageName>", "The name of the package whose runs to list.")
+      .argument(
+         "[versionId]",
+         "Optional version to filter runs to (e.g. 0.1.21). Omit to list every run in the package.",
+      )
+      .option("--debug")
+      .option(
+         "--source <sourceName>",
+         "Only list runs targeting this persist source.",
+      )
+      .option(
+         "--dimension <dimension>",
+         "Only list runs targeting this indexed dimension.",
+      )
+      .option(
+         "--measure <measure>",
+         "Only list runs targeting this pre-aggregated measure.",
+      )
+      // No static defaults — see the note on `ls index` above: a "-1" --page-size default
+      // makes parsePaginationParams ignore a lone --page N. Undefined keeps the all-records
+      // default while honoring --page N.
+      .option("--page <number>", `Page number (starts at ${DEFAULT_PAGE})`)
+      .option(
+         "--page-size <number>",
+         `Items per page (default: all records, max: 500)`,
+      )
+      .action((packageName, versionId, options) => {
+         listRuns(
+            controlPlanesByEnv[environment],
+            packageName,
+            versionId,
+            options.debug,
+            options.source,
+            options.dimension,
+            options.measure,
+            options.page,
+            options.pageSize,
+         );
+      });
+
+   list
+      .command("permission")
+      .alias("permissions")
+      .description(
+         "List the permissions on the organization, an environment, or a package.",
+      )
+      .option(
+         "--environment <environmentName>",
+         "List this environment's permissions instead of the organization's.",
+      )
+      .option(
+         "--package <packageName>",
+         "List this package's permissions. Uses --environment, or the current environment.",
+      )
+      .option("--debug")
+      .action((options) => {
+         listPermissions(controlPlanesByEnv[environment], options.debug, {
+            environment: options.environment,
+            package: options.package,
+         });
+      });
+
    list
       .command("group")
       .alias("groups")

package/src/commands/materialization/cancelrun.ts

@@ -0,0 +1,70 @@
+import { RunsApi, RunActionActionEnum } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import { getConfirmation, prettifyJson, printOutError } from "../../utils";
+
+const runsApi = new RunsApi(new Configuration());
+
+/**
+ * Cancel an in-flight (non-terminal) build/refresh run. No-op-safe: the control
+ * plane returns 409 if the run is already terminal. Prints the run's updated
+ * state.
+ */
+export async function cancelRun(
+   controlPlane: string,
+   packagePath: string,
+   runId: string,
+   debug: boolean,
+   autoConfirm: boolean,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   if (!runId) {
+      logger.error("Please provide a run ID");
+      return;
+   }
+
+   const packageName = packagePath.replace("/", "");
+
+   if (!autoConfirm) {
+      const confirmation = await getConfirmation(
+         `Cancel run ${runId} in ${packageName}?`,
+      );
+      if (!confirmation) {
+         return;
+      }
+   }
+
+   logger.info(`Cancelling run ${runId} in ${packageName}`);
+   try {
+      const response = await runsApi.runAction(
+         organizationName,
+         environmentName,
+         packageName,
+         runId,
+         RunActionActionEnum.Cancel,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to cancel run");
+      printOutError(e, debug);
+   }
+}

package/src/commands/materialization/getindex.ts

@@ -0,0 +1,55 @@
+import { IndexesApi } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import { prettifyJson, printOutError } from "../../utils";
+
+const indexesApi = new IndexesApi(new Configuration());
+
+/**
+ * Get a single dimensional search index anchor (binding) by id. Prints the full
+ * anchor state — `status`/`error`, the indexed `sourceName`/`dimension`, the
+ * serving `rowCount` (indexed values) and `lastIndexedAt`, scope, freshness
+ * policy, and the `stale`/`staleSince`/`staleReasons` triple.
+ */
+export async function getIndex(
+   controlPlane: string,
+   packagePath: string,
+   versionId: string,
+   indexId: string,
+   debug: boolean,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   try {
+      const packageName = packagePath.replace("/", "");
+      const response = await indexesApi.getIndex(
+         organizationName,
+         environmentName,
+         packageName,
+         versionId,
+         indexId,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to get index");
+      printOutError(e, debug);
+   }
+}

package/src/commands/materialization/getmaterialization.ts

@@ -0,0 +1,57 @@
+import { MaterializationsApi } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import { prettifyJson, printOutError } from "../../utils";
+
+const materializationsApi = new MaterializationsApi(new Configuration());
+
+/**
+ * Get a single Malloy Persistence materialization anchor by id. Prints the full
+ * anchor state — `status`/`error`, the physical `materializedTableName` and its
+ * `connectionName` (the underlying warehouse table currently serving the
+ * source), the serving run/build number, scope, freshness policy, and the
+ * `stale`/`staleSince`/`staleReasons` triple — so the state of the derived table
+ * is inspectable from the CLI without opening the app.
+ */
+export async function getMaterialization(
+   controlPlane: string,
+   packagePath: string,
+   versionId: string,
+   materializationId: string,
+   debug: boolean,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   try {
+      const packageName = packagePath.replace("/", "");
+      const response = await materializationsApi.getMaterialization(
+         organizationName,
+         environmentName,
+         packageName,
+         versionId,
+         materializationId,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to get materialization");
+      printOutError(e, debug);
+   }
+}

package/src/commands/materialization/getpreaggregate.ts

@@ -0,0 +1,58 @@
+import { PreaggregatesApi } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import { prettifyJson, printOutError } from "../../utils";
+
+const preaggregatesApi = new PreaggregatesApi(new Configuration());
+
+/**
+ * Get a single pre-aggregated measure by id. Prints its full state — `status`/`error`,
+ * the authored `sourceName` and `measure`, the `grainDimensions` it is rolled up to, the
+ * serving table and its `rowCount`/`lastBuiltAt`, scope, freshness policy, and the
+ * `stale`/`staleSince`/`staleReasons` triple.
+ *
+ * <p>The id is opaque and comes from `cred ls preaggregate` — it addresses a measure
+ * within a rollup, not the rollup table, so do not construct one by hand.
+ */
+export async function getPreaggregate(
+   controlPlane: string,
+   packagePath: string,
+   versionId: string,
+   preaggregateId: string,
+   debug: boolean,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   try {
+      const packageName = packagePath.replace("/", "");
+      const response = await preaggregatesApi.getPreaggregate(
+         organizationName,
+         environmentName,
+         packageName,
+         versionId,
+         preaggregateId,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to get pre-aggregation");
+      printOutError(e, debug);
+   }
+}

package/src/commands/materialization/getrun.ts

@@ -0,0 +1,55 @@
+import { RunsApi } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import { prettifyJson, printOutError } from "../../utils";
+
+const runsApi = new RunsApi(new Configuration());
+
+/**
+ * Get a single build/refresh run by id, including its stateful build plan. The
+ * `buildPlan.nodes` carry each produced unit's live state — per source node the
+ * physical `tableName` and `rowCount`, per index node the dimension and its
+ * status — and `buildPlan.edges` wire sources to the indexes that depend on
+ * them. This is the detailed view (`listRuns` omits the graph); use it to see
+ * exactly which physical tables a run produced and how the units relate.
+ */
+export async function getRun(
+   controlPlane: string,
+   packagePath: string,
+   runId: string,
+   debug: boolean,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   try {
+      const packageName = packagePath.replace("/", "");
+      const response = await runsApi.getRun(
+         organizationName,
+         environmentName,
+         packageName,
+         runId,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to get run");
+      printOutError(e, debug);
+   }
+}

package/src/commands/materialization/listindexes.ts

@@ -0,0 +1,69 @@
+import { IndexesApi } from "../../client/api";
+import { Configuration } from "../../client/configuration";
+import { ClientConfiguration } from "../../clientconfiguration";
+import { logger } from "../../logger";
+import {
+   prettifyJson,
+   printOutError,
+   parsePaginationParams,
+   extractTotalCount,
+} from "../../utils";
+
+const indexesApi = new IndexesApi(new Configuration());
+
+/**
+ * List the dimensional search indexes bound to a package version (the per-`#(index)`
+ * serving anchors). Each entry prints its `status` and, when FAILED, the `error`;
+ * plus the serving `rowCount`, `lastIndexedAt`, freshness policy, and the
+ * `stale`/`staleReasons` triple — so a failing or stale index is diagnosable
+ * from the CLI. The total available count is logged to stderr.
+ */
+export async function listIndexes(
+   controlPlane: string,
+   packagePath: string,
+   versionId: string,
+   debug: boolean,
+   page?: string | number,
+   pageSize?: string | number,
+) {
+   const clientConfig = new ClientConfiguration();
+   const organizationName = clientConfig.getOrganization();
+   const environmentName = clientConfig.getProject();
+
+   if (!clientConfig.doesConfigExists()) {
+      logger.error("Please, make sure that you are logged in");
+      return;
+   }
+
+   if (!environmentName) {
+      logger.error("Please, make sure to set an environment");
+      return;
+   }
+
+   try {
+      const packageName = packagePath.replace("/", "");
+      const { limit, offset } = parsePaginationParams(page, pageSize);
+      const response = await indexesApi.listIndexes(
+         organizationName,
+         environmentName,
+         packageName,
+         versionId,
+         limit,
+         offset,
+         {
+            baseURL: controlPlane,
+            headers: clientConfig.getHeaders(),
+         },
+      );
+
+      const totalCount = extractTotalCount(response.headers);
+      if (totalCount !== undefined) {
+         logger.info(`Total indexes available: ${totalCount}`);
+      }
+
+      console.log(prettifyJson(response.data));
+   } catch (e) {
+      logger.error("Failed to list indexes");
+      printOutError(e, debug);
+   }
+}