@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/src/config/getProjectConfig.ts

@@ -12,7 +12,7 @@ import {
 } from "@catladder/pipeline";
 
 import type { IO } from "../core/types";
-import { getAllVariables, getVariableValueByRawName } from "../utils/gitlab";
+import { getVariableValueByRawName } from "../utils/gitlab";
 
 import { getGitRoot } from "../utils/projects";
 
@@ -39,6 +39,15 @@ export const getProjectConfig = async () => {
   return currentConfig as Config;
 };
 
+/**
+ * drops the cached config so the next access re-reads it from disk —
+ * needed after writing the catladder store, which is attached to the
+ * config (`config.store`) at read time
+ */
+export const invalidateProjectConfig = () => {
+  currentConfig = null;
+};
+
 export const getProjectComponents = async () => {
   const config = await getProjectConfig();
   if (!config) return [];
@@ -121,10 +130,24 @@ export const getGitlabVar = async (
 };
 
 const resolveSecrets = async (
-  io: IO | null,
+  io: IO,
   varSets: EnvironmentEnvVars[],
 ): Promise<Record<string, string>> => {
-  const allVariablesInGitlab = await getAllVariables(io);
+  // the secret variables actually referenced by the env var values —
+  // when they are all in the local cache, the vault is not contacted
+  const referencedNames = [
+    ...new Set(
+      varSets.flatMap(({ envVars }) =>
+        Object.values(envVars).flatMap(
+          (value) => `${value}`.match(/\$CL_\w+/g) ?? [],
+        ),
+      ),
+    ),
+  ].map((reference) => reference.slice(1));
+
+  const vaultManager = await io.getVaultManager();
+  const secrets = await vaultManager.readSecrets(referencedNames, io);
+  const secretEntries = Object.entries(secrets);
 
   return Object.fromEntries(
     varSets.flatMap(({ envVars, secretEnvVarKeys }) =>
@@ -137,9 +160,9 @@ const resolveSecrets = async (
         )
         .map(([key, value]) => [
           key,
-          allVariablesInGitlab.reduce(
-            (acc, curr) =>
-              acc.replace(new RegExp("\\$" + curr.key, "g"), curr.value),
+          secretEntries.reduce(
+            (acc, [name, secretValue]) =>
+              acc.replace(new RegExp("\\$" + name, "g"), secretValue),
             `${value}`,
           ),
         ]),
@@ -148,7 +171,7 @@ const resolveSecrets = async (
 };
 
 export const getEnvVarsResolved = async (
-  io: IO | null,
+  io: IO,
   env: string,
   componentName: string | null,
 ) => {

package/src/core/types.ts

@@ -1,3 +1,4 @@
+import type { VaultManager } from "../vault/VaultManager";
 import type { ComponentContext } from "@catladder/pipeline";
 
 // ─── Input Definitions ───────────────────────────────────────────────
@@ -76,6 +77,19 @@ export type InputsSchema = Record<string, InputDef>;
  * that are NOT part of a command's declared input schema.
  */
 export interface IO {
+  /**
+   * whether this context can interact with the user (prompts, editors).
+   * Non-interactive contexts throw {@link NonInteractiveError} when an
+   * interaction would be required.
+   */
+  readonly interactive: boolean;
+
+  /**
+   * the secrets vault of this context, created lazily from the project
+   * config
+   */
+  getVaultManager(): Promise<VaultManager>;
+
   log(message: string): void;
   /**
    * Ask for confirmation. Returns true/false.
@@ -131,6 +145,15 @@ export interface CommandDef<TInputs extends InputsSchema = InputsSchema> {
 
 // ─── Errors ──────────────────────────────────────────────────────────
 
+export class NonInteractiveError extends Error {
+  constructor(interaction: string) {
+    super(
+      `${interaction} requires an interactive terminal, but this context is not interactive`,
+    );
+    this.name = "NonInteractiveError";
+  }
+}
+
 export class MissingInputError extends Error {
   constructor(
     public readonly inputName: string,

package/src/gcloud/__tests__/serviceAccountNames.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { getGcloudServiceAccountNames } from "../serviceAccountNames";
+
+// the naming is shared between `project setup` (creates accounts) and
+// `project doctor` (computes the expected identifier) — these tests pin
+// it down so a change never silently makes doctor look for accounts
+// under a different name than setup created them
+
+const account = { name: "cl-d", projectId: "some-project" };
+
+describe("getGcloudServiceAccountNames", () => {
+  it("keeps all parts verbatim when they fit into 30 chars", () => {
+    const { fullName, fullIdentifier } = getGcloudServiceAccountNames(
+      {
+        env: "dev",
+        name: "www",
+        fullConfig: { customerName: "acme", appName: "shop" },
+      },
+      account,
+    );
+    expect(fullName).toBe("cl-d-acme-shop-dev-www");
+    expect(fullIdentifier).toBe(
+      "cl-d-acme-shop-dev-www@some-project.iam.gserviceaccount.com",
+    );
+  });
+
+  it("hashes the customer/app middle part when the name would exceed 30 chars", () => {
+    const { fullName } = getGcloudServiceAccountNames(
+      {
+        env: "review",
+        name: "outlet-stats",
+        fullConfig: { customerName: "wea", appName: "food2050" },
+      },
+      account,
+    );
+    expect(fullName).toMatch(/^cl-d-[0-9a-f]{5}-review-outlet-stats$/);
+    expect(fullName.length).toBe(30);
+  });
+
+  it("hashes the env/component suffix too when a 1-char middle still does not fit", () => {
+    const { fullName } = getGcloudServiceAccountNames(
+      {
+        env: "review",
+        name: "a-component-with-a-very-long-name",
+        fullConfig: { customerName: "customer", appName: "app" },
+      },
+      account,
+    );
+    expect(fullName).toMatch(/^cl-d-[0-9a-f]-[0-9a-f]{23}$/);
+    expect(fullName.length).toBe(30);
+  });
+
+  it("is deterministic", () => {
+    const context = {
+      env: "review",
+      name: "outlet-stats",
+      fullConfig: { customerName: "wea", appName: "food2050" },
+    };
+    expect(getGcloudServiceAccountNames(context, account)).toEqual(
+      getGcloudServiceAccountNames(context, account),
+    );
+  });
+});

package/src/gcloud/artifactsRegistry.ts

@@ -1,13 +1,15 @@
 import type { Gcloudregion } from "@catladder/pipeline";
 import { exec } from "child-process-promise";
 
+export const CATLADDER_REGISTRY_NAME = "catladder-deploy";
+
 export const upsertGcloudArtifactsRegistry = async (config: {
   projectId: string;
   region: Gcloudregion;
 }) => {
   try {
     await exec(
-      `gcloud artifacts repositories create catladder-deploy --project="${config.projectId}" --repository-format=docker --location=${config.region}`,
+      `gcloud artifacts repositories create ${CATLADDER_REGISTRY_NAME} --project="${config.projectId}" --repository-format=docker --location=${config.region}`,
     );
   } catch (e) {
     // probably already exists

package/src/gcloud/getProjectNumber.ts

@@ -0,0 +1,20 @@
+import { exec } from "child-process-promise";
+
+/**
+ * resolves the numeric gcloud project number for a project id.
+ * Requires `cloudresourcemanager.googleapis.com` to be enabled.
+ */
+export const fetchGcloudProjectNumber = async (
+  projectId: string,
+): Promise<string> => {
+  const result = await exec(
+    `gcloud projects describe ${projectId} --format="value(projectNumber)"`,
+  );
+  const projectNumber = result.stdout.trim();
+  if (!/^\d+$/.test(projectNumber)) {
+    throw new Error(
+      `could not determine the gcloud project number for "${projectId}" (got: "${projectNumber}")`,
+    );
+  }
+  return projectNumber;
+};

package/src/gcloud/serviceAccountNames.ts

@@ -0,0 +1,65 @@
+import { createHmac } from "crypto";
+
+/**
+ * the parts of a component context the naming depends on — structural
+ * subset of `ComponentContext` so the naming stays a pure function
+ */
+export type ServiceAccountNamingContext = {
+  env: string;
+  name: string;
+  fullConfig: { customerName: string; appName: string };
+};
+
+/**
+ * the deterministic gcloud service account naming used by
+ * `project setup`. Extracted so `project doctor` can compute the
+ * expected identifier of an account without creating anything.
+ *
+ * gcloud limits account ids to 30 chars: the customer/app middle part
+ * (and, if even that is not enough, the env/component suffix) is
+ * replaced by a hash when the full name would not fit.
+ */
+export const getGcloudServiceAccountNames = (
+  context: ServiceAccountNamingContext,
+  account: { name: string; projectId: string },
+): { fullName: string; fullIdentifier: string } => {
+  const { projectId, name } = account;
+
+  // name has limit of 30
+  const namePrefix = `${name}`;
+  const nameSuffixRaw = `${context.env}-${context.name}`;
+  const nameMiddleRaw = `${context.fullConfig.customerName}-${context.fullConfig.appName}`;
+  const MAX_LENGTH = 30;
+  const NUM_SEPARATORS = 2;
+
+  // we want to first hash middle, then suffix
+  // if for middle we have at least 1 char left, its ok, so we don't hash nameSuffix, otherwise we need to hash that as well
+
+  const middleMaxLength =
+    MAX_LENGTH - namePrefix.length - nameSuffixRaw.length - NUM_SEPARATORS;
+
+  let nameMiddle: string;
+  let nameSuffix: string;
+  if (middleMaxLength < 1) {
+    nameMiddle = hashIfNessecary(nameMiddleRaw, 1);
+    nameSuffix = hashIfNessecary(
+      nameSuffixRaw,
+      MAX_LENGTH - namePrefix.length - 1 - NUM_SEPARATORS,
+    );
+  } else {
+    nameMiddle = hashIfNessecary(nameMiddleRaw, middleMaxLength);
+    nameSuffix = nameSuffixRaw;
+  }
+
+  const fullName = `${namePrefix}-${nameMiddle}-${nameSuffix}`;
+  const fullIdentifier = `${fullName}@${projectId}.iam.gserviceaccount.com`;
+
+  return { fullName, fullIdentifier };
+};
+
+const hashIfNessecary = (str: string, maxLength: number) =>
+  str.length > maxLength ? hash(str, maxLength) : str;
+
+const hash = (str: string, length: number) => {
+  return createHmac("sha256", str).digest("hex").substring(0, length);
+};

package/src/gcloud/serviceAccounts.ts

@@ -1,9 +1,9 @@
 import type { ComponentContext } from "@catladder/pipeline";
 
 import { exec } from "child-process-promise";
-import { createHmac } from "crypto";
 import type { IO } from "../core/types";
 import { upsertAllVariables } from "../utils/gitlab";
+import { getGcloudServiceAccountNames } from "./serviceAccountNames";
 
 export const accountExists = async (fullIdentifier: string) => {
   try {
@@ -25,40 +25,15 @@ const upsertGcloudServiceAccount = async (
   context: ComponentContext,
   account: ServiceAccount,
 ): Promise<string> => {
-  const { projectId, name, displayName, roles, description } = account;
+  const { projectId, displayName, roles, description } = account;
 
-  // name has limit of 30
-  const namePrefix = `${name}`;
-  const nameSuffixRaw = `${context.env}-${context.name}`;
-  const nameMiddleRaw = `${context.fullConfig.customerName}-${context.fullConfig.appName}`;
-  const MAX_LENGTH = 30;
-  const NUM_SEPARATORS = 2;
-
-  // we want to first hash middle, then suffix
-  // if for middle we have at least 1 char left, its ok, so we don't hash nameSuffix, otherwise we need to hash that as well
-
-  const middleMaxLength =
-    MAX_LENGTH - namePrefix.length - nameSuffixRaw.length - NUM_SEPARATORS;
-
-  let nameMiddle: string;
-  let nameSuffix: string;
-  if (middleMaxLength < 1) {
-    nameMiddle = hashIfNessecary(nameMiddleRaw, 1);
-    nameSuffix = hashIfNessecary(
-      nameSuffixRaw,
-      MAX_LENGTH - namePrefix.length - 1 - NUM_SEPARATORS,
-    );
-  } else {
-    nameMiddle = hashIfNessecary(nameMiddleRaw, middleMaxLength);
-    nameSuffix = nameSuffixRaw;
-  }
-
-  const fullName = `${namePrefix}-${nameMiddle}-${nameSuffix}`;
+  const { fullName, fullIdentifier } = getGcloudServiceAccountNames(
+    context,
+    account,
+  );
 
   const fullDisplayName = `${context.fullConfig.customerName}-${context.fullConfig.appName} ${context.env}:${context.name} | ${displayName}`;
 
-  const fullIdentifier = `${fullName}@${projectId}.iam.gserviceaccount.com`;
-
   const existing = await accountExists(fullIdentifier);
 
   if (!existing) {
@@ -111,10 +86,3 @@ export const upsertGcloudServiceAccountAndSaveSecret = async (
   );
   instance.log("done!");
 };
-
-const hashIfNessecary = (str: string, maxLength: number) =>
-  str.length > maxLength ? hash(str, maxLength) : str;
-
-const hash = (str: string, length: number) => {
-  return createHmac("sha256", str).digest("hex").substring(0, length);
-};

package/src/git/gitProjectInformation.ts

@@ -12,17 +12,19 @@ export const getProjectRootPath = async (): Promise<string> => {
 /**
  * Get the git remote hostname and project path from the git config.
  */
-export const getGitRemoteHostAndPath = async (): Promise<{
+export const getGitRemoteHostAndPath = async (
+  remoteName = "origin",
+): Promise<{
   gitRemoteHost: string;
   gitRemotePath: string;
 }> => {
-  const remoteUrl = await gitConfigGet("remote.origin.url");
+  const remoteUrl = await gitConfigGet(`remote.${remoteName}.url`);
   const remoteReg = /(https:\/\/|git@)([^:/]+)[:/]([^.]*)(\.git)?/;
   const match = remoteUrl.match(remoteReg) ?? [];
   const [, , gitRemoteHost, gitRemotePath] = match;
   if (!gitRemoteHost?.length || !gitRemotePath?.length) {
     throw new Error(
-      `Failed to parse git remote hostname and path from git configs remote.origin.url! ${remoteUrl}`,
+      `Failed to parse git remote hostname and path from git configs remote.${remoteName}.url! ${remoteUrl}`,
     );
   }
   return { gitRemoteHost, gitRemotePath };

package/src/publish/__tests__/npmPublishPlan.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { computeNpmPublishPlan, slugifyRef } from "../npmPublishPlan";
+import { parseNpmPublishArgs } from "../npmPublishJob";
+
+describe("computeNpmPublishPlan", () => {
+  it("publishes the tag version as latest for prod", () => {
+    expect(
+      computeNpmPublishPlan({
+        envType: "prod",
+        ciTag: "v5.1.2",
+        refSlug: "v5-1-2",
+        shortSha: "abcd1234",
+      }),
+    ).toEqual({ version: "5.1.2", distTag: "latest" });
+  });
+
+  it("fails for prod without a git tag", () => {
+    expect(() =>
+      computeNpmPublishPlan({
+        envType: "prod",
+        ciTag: null,
+        refSlug: "main",
+        shortSha: "abcd1234",
+      }),
+    ).toThrow(/tagged-release/);
+  });
+
+  it("publishes branch canaries under the canary dist-tag", () => {
+    expect(
+      computeNpmPublishPlan({
+        envType: "dev",
+        ciTag: null,
+        refSlug: "main",
+        shortSha: "abcd1234",
+      }),
+    ).toEqual({ version: "0.0.0-main-abcd1234", distTag: "canary" });
+  });
+
+  it("publishes MR canaries (review env) under the canary dist-tag", () => {
+    expect(
+      computeNpmPublishPlan({
+        envType: "review",
+        ciTag: null,
+        refSlug: "feat-cool-thing",
+        shortSha: "abcd1234",
+      }),
+    ).toEqual({ version: "0.0.0-feat-cool-thing-abcd1234", distTag: "canary" });
+  });
+
+  it("gives next/beta branches their own dist-tag", () => {
+    expect(
+      computeNpmPublishPlan({
+        envType: "dev",
+        ciTag: null,
+        refSlug: "next",
+        shortSha: "abcd1234",
+      }),
+    ).toEqual({ version: "0.0.0-next-abcd1234", distTag: "next" });
+    expect(
+      computeNpmPublishPlan({
+        envType: "dev",
+        ciTag: null,
+        refSlug: "beta",
+        shortSha: "abcd1234",
+      }).distTag,
+    ).toBe("beta");
+  });
+
+  it("lets an explicit dist-tag override the derivation", () => {
+    expect(
+      computeNpmPublishPlan({
+        envType: "dev",
+        ciTag: null,
+        refSlug: "main",
+        shortSha: "abcd1234",
+        distTagOverride: "nightly",
+      }).distTag,
+    ).toBe("nightly");
+    expect(
+      computeNpmPublishPlan({
+        envType: "prod",
+        ciTag: "v2.0.0",
+        refSlug: "v2-0-0",
+        shortSha: "abcd1234",
+        distTagOverride: "lts",
+      }).distTag,
+    ).toBe("lts");
+  });
+});
+
+describe("slugifyRef", () => {
+  it("mirrors gitlab's ref slug derivation", () => {
+    expect(slugifyRef("feat/My_Cool-Branch!")).toBe("feat-my-cool-branch");
+    expect(slugifyRef("main")).toBe("main");
+    expect(slugifyRef("-weird--")).toBe("weird");
+  });
+});
+
+describe("parseNpmPublishArgs", () => {
+  it("parses the generated flag list", () => {
+    expect(
+      parseNpmPublishArgs([
+        "--dir",
+        "apps/cli",
+        "--env-type",
+        "dev",
+        "--access",
+        "public",
+      ]),
+    ).toEqual({
+      dir: "apps/cli",
+      envType: "dev",
+      access: "public",
+      registry: undefined,
+      distTag: undefined,
+    });
+  });
+
+  it("rejects missing required flags", () => {
+    expect(parseNpmPublishArgs(["--dir", "apps/cli"])).toBeNull();
+    expect(parseNpmPublishArgs(["--dir"])).toBeNull();
+  });
+});

package/src/publish/npmPublishJob.ts

@@ -0,0 +1,167 @@
+/**
+ * the npmPackage deploy CI job (run by catci: `catci publish npm`):
+ * derives version + dist-tag from the pipeline trigger, stamps the
+ * version into the package's package.json and runs `npm publish`.
+ */
+import { spawn } from "child_process";
+import { readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import type { NpmPublishContext } from "./npmPublishPlan";
+import { computeNpmPublishPlan, slugifyRef } from "./npmPublishPlan";
+
+export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+
+export type NpmPublishJobOptions = {
+  dir: string;
+  envType: string;
+  access?: string;
+  registry?: string;
+  distTag?: string;
+};
+
+/**
+ * reads the trigger context from the CI provider's predefined
+ * variables (gitlab or github)
+ */
+const readCiContext = (
+  options: NpmPublishJobOptions,
+): Omit<NpmPublishContext, "envType" | "distTagOverride"> => {
+  const env = process.env;
+  if (env.GITLAB_CI === "true") {
+    return {
+      ciTag: env.CI_COMMIT_TAG || null,
+      refSlug: env.CI_COMMIT_REF_SLUG ?? "",
+      shortSha: env.CI_COMMIT_SHORT_SHA ?? "",
+    };
+  }
+  if (env.GITHUB_ACTIONS === "true") {
+    return {
+      ciTag:
+        env.GITHUB_REF_TYPE === "tag" ? (env.GITHUB_REF_NAME ?? null) : null,
+      // GITHUB_HEAD_REF is the source branch on pull_request events
+      refSlug: slugifyRef(env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME || ""),
+      shortSha: (env.GITHUB_SHA ?? "").slice(0, 8),
+    };
+  }
+  throw new Error(
+    `publish npm for "${options.dir}" must run in a gitlab or github CI job (no CI provider detected)`,
+  );
+};
+
+const setPackageVersion = async (dir: string, version: string) => {
+  const packageJsonPath = join(dir, "package.json");
+  const pkg = JSON.parse(await readFile(packageJsonPath, "utf-8"));
+  pkg.version = version;
+  await writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+  return pkg.name as string;
+};
+
+/**
+ * writes the auth .npmrc and returns its absolute path. It is passed to
+ * npm as userconfig: in a workspace monorepo npm resolves its project
+ * prefix to the workspace ROOT, so a package-local .npmrc would be
+ * silently ignored (ENEEDAUTH). npm expands `${NPM_TOKEN}` from the job
+ * environment at run time and never includes .npmrc in the tarball.
+ */
+const writeNpmrc = async (dir: string, registry: string) => {
+  const registryHost = registry.replace(/^https?:/, "").replace(/\/?$/, "/");
+  const npmrcPath = resolve(dir, ".npmrc");
+  await writeFile(
+    npmrcPath,
+
+    `${registryHost}:_authToken=\${NPM_TOKEN}\n`,
+  );
+  return npmrcPath;
+};
+
+/**
+ * whether the CI job can mint an OIDC token for npm trusted publishing.
+ * github actions exposes these two only when the job declares
+ * `permissions: id-token: write` (catladder sets it via the job's
+ * `idToken` flag).
+ */
+const hasOidcCredentials = () =>
+  !!process.env.ACTIONS_ID_TOKEN_REQUEST_URL &&
+  !!process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+
+const npmPublish = (
+  dir: string,
+  npmrcPath: string | undefined,
+  args: string[],
+) =>
+  new Promise<void>((resolvePromise, reject) => {
+    const child = spawn("npm", ["publish", ...args], {
+      cwd: dir,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        ...(npmrcPath ? { NPM_CONFIG_USERCONFIG: npmrcPath } : {}),
+      },
+    });
+    child.on("error", reject);
+    child.on("exit", (code) =>
+      code === 0
+        ? resolvePromise()
+        : reject(new Error(`npm publish exited with ${code}`)),
+    );
+  });
+
+export const npmPublishJob = async (options: NpmPublishJobOptions) => {
+  const oidc = hasOidcCredentials();
+  if (!oidc && !process.env.NPM_TOKEN) {
+    throw new Error(
+      "NPM_TOKEN is not set — configure it as a catladder secret for this component, or publish from a workflow registered as a trusted publisher on npm",
+    );
+  }
+  const registry = options.registry ?? DEFAULT_NPM_REGISTRY;
+  const plan = computeNpmPublishPlan({
+    envType: options.envType,
+    distTagOverride: options.distTag,
+    ...readCiContext(options),
+  });
+
+  const name = await setPackageVersion(options.dir, plan.version);
+  // with OIDC available npm mints its own short-lived credentials, and
+  // an .npmrc referencing an unset ${NPM_TOKEN} would only get in the
+  // way. A token, when present, still wins as the fallback.
+  const npmrcPath =
+    oidc && !process.env.NPM_TOKEN
+      ? undefined
+      : await writeNpmrc(options.dir, registry);
+
+  console.log(
+    `publishing ${name}@${plan.version} (dist-tag ${plan.distTag}) to ${registry}${
+      npmrcPath ? "" : " via trusted publishing (OIDC)"
+    }`,
+  );
+  await npmPublish(options.dir, npmrcPath, [
+    "--tag",
+    plan.distTag,
+    "--access",
+    options.access ?? "public",
+    "--registry",
+    registry,
+    // publish exactly this package, not the workspace set npm may
+    // otherwise derive from the monorepo root
+    "--workspaces=false",
+  ]);
+  console.log(`published ${name}@${plan.version} 🚀`);
+};
+
+/** parses the `catci publish npm --flag value ...` argument list */
+export const parseNpmPublishArgs = (
+  args: string[],
+): NpmPublishJobOptions | null => {
+  const options: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    const value = args[i + 1];
+    if (!flag?.startsWith("--") || value === undefined) return null;
+    options[flag.slice(2)] = value;
+  }
+  const { dir, access, registry } = options;
+  const envType = options["env-type"];
+  const distTag = options["dist-tag"];
+  if (!dir || !envType) return null;
+  return { dir, envType, access, registry, distTag };
+};