@jsdevtools/npm-publish 1.4.3 → 2.1.0

package/src/action/main.ts

@@ -0,0 +1,32 @@
+/** Action entry point */
+import { npmPublish } from "../index.js";
+import * as core from "./core.js";
+
+/** Run the action. */
+async function run(): Promise<void> {
+  const results = await npmPublish({
+    token: core.getRequiredSecretInput("token"),
+    registry: core.getInput("registry"),
+    package: core.getInput("package"),
+    tag: core.getInput("tag"),
+    access: core.getInput("access"),
+    provenance: core.getBooleanInput("provenance"),
+    strategy: core.getInput("strategy"),
+    dryRun: core.getBooleanInput("dry-run"),
+    logger: core.logger,
+    temporaryDirectory: process.env["RUNNER_TEMP"],
+  });
+
+  core.setOutput("id", results.id, "");
+  core.setOutput("name", results.name);
+  core.setOutput("version", results.version);
+  core.setOutput("type", results.type, "");
+  core.setOutput("old-version", results.oldVersion, "");
+  core.setOutput("registry", results.registry.href);
+  core.setOutput("tag", results.tag);
+  core.setOutput("access", results.access, "default");
+  core.setOutput("strategy", results.strategy);
+  core.setOutput("dry-run", results.dryRun);
+}
+
+run().catch((error: Error) => core.setFailed(error));

package/src/cli/index.ts

@@ -0,0 +1,72 @@
+import { npmPublish, type Logger } from "../index.js";
+import { parseCliArguments } from "./parse-cli-arguments.js";
+
+export const USAGE = `
+Usage:
+
+  npm-publish <options> [package]
+
+Arguments:
+
+  package                 The path to the package to publish.
+                          May be a directory, package.json, or .tgz file.
+                          Defaults to the package in the current directory.
+
+Options:
+
+  --token <token>         (Required) npm authentication token.
+
+  --registry <url>        Registry to read from and write to.
+                          Defaults to "https://registry.npmjs.org/".
+
+  --tag <tag>             The distribution tag to check against and publish to.
+                          Defaults to "latest".
+
+  --access <access>       Package access, may be "public" or "restricted".
+                          See npm documentation for details.
+
+  --provenance            Publish with provenance statements.
+                          See npm documentation for details.
+
+  --strategy <strategy>   Publish strategy, may be "all" or "upgrade".
+                          Defaults to "all", see documentation for details.
+
+  --dry-run               Do not actually publish anything.
+  --quiet                 Only print errors.
+  --debug                 Print debug logs.
+
+  -v, --version           Print the version number.
+  -h, --help              Show usage text.
+
+Examples:
+
+  $ npm-publish --token abc123 ./my-package
+`;
+
+/**
+ * The main entry point of the CLI
+ *
+ * @param argv - The list of argument strings passed to the program.
+ * @param version - The version of this program.
+ */
+export async function main(argv: string[], version: string): Promise<void> {
+  const cliArguments = parseCliArguments(argv);
+
+  if (cliArguments.help) {
+    console.info(USAGE);
+    return;
+  }
+
+  if (cliArguments.version) {
+    console.info(version);
+    return;
+  }
+
+  const logger: Logger = {
+    error: console.error,
+    info: cliArguments.quiet === false ? console.info : undefined,
+    debug: cliArguments.debug === true ? console.debug : undefined,
+  };
+
+  await npmPublish({ ...cliArguments.options, logger });
+}

package/src/cli/parse-cli-arguments.ts

@@ -0,0 +1,49 @@
+/** Wrapper module for command-line-args */
+
+import commandLineArgs from "command-line-args";
+import type { Options } from "../options.js";
+
+const ARGUMENTS_OPTIONS = [
+  { name: "package", type: String, defaultOption: true },
+  { name: "token", type: String },
+  { name: "registry", type: String },
+  { name: "tag", type: String },
+  { name: "access", type: String },
+  { name: "provenance", type: Boolean },
+  { name: "strategy", type: String },
+  { name: "dry-run", type: Boolean },
+  { name: "quiet", type: Boolean },
+  { name: "debug", type: Boolean },
+  { name: "version", alias: "v", type: Boolean },
+  { name: "help", alias: "h", type: Boolean },
+];
+
+/** The parsed command-line arguments */
+export interface ParsedArguments {
+  help?: boolean;
+  version?: boolean;
+  quiet?: boolean;
+  debug?: boolean;
+  options: Options;
+}
+
+/**
+ * Parse the given command-line arguments.
+ *
+ * @param argv The list of argument strings passed to the program.
+ * @returns A parsed object of options.
+ */
+export function parseCliArguments(argv: string[]): ParsedArguments {
+  const { help, version, quiet, debug, ...options } = commandLineArgs(
+    ARGUMENTS_OPTIONS,
+    { argv, camelCase: true }
+  );
+
+  return {
+    help: Boolean(help),
+    version: Boolean(version),
+    quiet: Boolean(quiet),
+    debug: Boolean(debug),
+    options: options as Options,
+  };
+}

package/src/compare-and-publish/compare-and-publish.ts

@@ -0,0 +1,75 @@
+import type { PackageManifest } from "../read-manifest.js";
+import type { NormalizedOptions } from "../normalize-options.js";
+import {
+  VIEW,
+  PUBLISH,
+  E404,
+  EPUBLISHCONFLICT,
+  callNpmCli,
+  type NpmCliEnvironment,
+} from "../npm/index.js";
+import { compareVersions, type VersionComparison } from "./compare-versions.js";
+import { getViewArguments, getPublishArguments } from "./get-arguments.js";
+
+export interface PublishResult extends VersionComparison {
+  id: string | undefined;
+  files: PublishFile[];
+}
+
+export interface PublishFile {
+  path: string;
+  size: number;
+}
+
+/**
+ * Get the currently published versions of a package and publish if needed.
+ *
+ * @param manifest The package to potentially publish.
+ * @param options Configuration options.
+ * @param environment Environment variables for the npm cli.
+ * @returns Information about the publish, including if it occurred.
+ */
+export async function compareAndPublish(
+  manifest: PackageManifest,
+  options: NormalizedOptions,
+  environment: NpmCliEnvironment
+): Promise<PublishResult> {
+  const { name, version, packageSpec } = manifest;
+  const cliOptions = { environment, logger: options.logger };
+
+  const viewArguments = getViewArguments(name, options);
+  const publishArguments = getPublishArguments(packageSpec, options);
+  let viewCall = await callNpmCli(VIEW, viewArguments, cliOptions);
+
+  // `npm view` will succeed with no output the package exists in the registry
+  // with no `latest` tag. This is only possible with third-party registries.
+  // https://github.com/npm/cli/issues/6408
+  if (!viewCall.successData && !viewCall.error) {
+    // Retry the call to `npm view` with the configured publish tag,
+    // to at least try to get something.
+    const viewWithTagArguments = getViewArguments(name, options, true);
+    viewCall = await callNpmCli(VIEW, viewWithTagArguments, cliOptions);
+  }
+
+  if (viewCall.error && viewCall.errorCode !== E404) {
+    throw viewCall.error;
+  }
+
+  const comparison = compareVersions(version, viewCall.successData, options);
+  const publishCall = comparison.type
+    ? await callNpmCli(PUBLISH, publishArguments, cliOptions)
+    : { successData: undefined, errorCode: undefined, error: undefined };
+
+  if (publishCall.error && publishCall.errorCode !== EPUBLISHCONFLICT) {
+    throw publishCall.error;
+  }
+
+  const { successData: publishData } = publishCall;
+
+  return {
+    id: publishData?.id,
+    files: publishData?.files ?? [],
+    type: publishData ? comparison.type : undefined,
+    oldVersion: comparison.oldVersion,
+  };
+}

package/src/compare-and-publish/compare-versions.ts

@@ -0,0 +1,48 @@
+import semverDifference from "semver/functions/diff.js";
+import semverGreaterThan from "semver/functions/gt.js";
+import semverValid from "semver/functions/valid.js";
+
+import { STRATEGY_ALL } from "../options.js";
+import type { NormalizedOptions } from "../normalize-options.js";
+import type { ReleaseType } from "../results.js";
+import type { NpmViewData } from "../npm/index.js";
+
+export interface VersionComparison {
+  type: ReleaseType | undefined;
+  oldVersion: string | undefined;
+}
+
+const INITIAL = "initial";
+const DIFFERENT = "different";
+
+/**
+ * Compare previously published versions with the package's current version.
+ *
+ * @param currentVersion The current package version.
+ * @param publishedVersions The versions that have already been published.
+ * @param options Configuration options
+ * @returns The release type and previous version.
+ */
+export function compareVersions(
+  currentVersion: string,
+  publishedVersions: NpmViewData | undefined,
+  options: NormalizedOptions
+): VersionComparison {
+  const { versions, "dist-tags": tags } = publishedVersions ?? {};
+  const { strategy, tag: publishTag } = options;
+  const oldVersion = semverValid(tags?.[publishTag.value]) ?? undefined;
+  const isUnique = !versions?.includes(currentVersion);
+  let type: ReleaseType | undefined;
+
+  if (isUnique) {
+    if (!oldVersion) {
+      type = INITIAL;
+    } else if (semverGreaterThan(currentVersion, oldVersion)) {
+      type = semverDifference(currentVersion, oldVersion) ?? DIFFERENT;
+    } else if (strategy.value === STRATEGY_ALL) {
+      type = DIFFERENT;
+    }
+  }
+
+  return { type, oldVersion };
+}

package/src/compare-and-publish/get-arguments.ts

@@ -0,0 +1,61 @@
+import type { NormalizedOptions } from "../normalize-options.js";
+
+/**
+ * Given a package name and publish configuration, get the NPM CLI view
+ * arguments.
+ *
+ * @param packageName Package name.
+ * @param options Publish configuration.
+ * @param retryWithTag Include a non-latest tag in the package spec for a rety
+ *   attempt.
+ * @returns Arguments to pass to the NPM CLI. If `retryWithTag` is true, but the
+ *   publish config is using the `latest` tag, will return `undefined`.
+ */
+export function getViewArguments(
+  packageName: string,
+  options: NormalizedOptions,
+  retryWithTag = false
+): string[] {
+  const packageSpec = retryWithTag
+    ? `${packageName}@${options.tag.value}`
+    : packageName;
+
+  return [packageSpec, "dist-tags", "versions"];
+}
+
+/**
+ * Given a publish configuration, get the NPM CLI publish arguments.
+ *
+ * @param packageSpec Package specification path.
+ * @param options Publish configuration.
+ * @returns Arguments to pass to the NPM CLI.
+ */
+export function getPublishArguments(
+  packageSpec: string,
+  options: NormalizedOptions
+): string[] {
+  const { tag, access, dryRun, provenance } = options;
+  const publishArguments = [];
+
+  if (packageSpec.length > 0) {
+    publishArguments.push(packageSpec);
+  }
+
+  if (!tag.isDefault) {
+    publishArguments.push("--tag", tag.value);
+  }
+
+  if (!access.isDefault && access.value) {
+    publishArguments.push("--access", access.value);
+  }
+
+  if (!provenance.isDefault && provenance.value) {
+    publishArguments.push("--provenance");
+  }
+
+  if (!dryRun.isDefault && dryRun.value) {
+    publishArguments.push("--dry-run");
+  }
+
+  return publishArguments;
+}

package/src/compare-and-publish/index.ts

@@ -0,0 +1 @@
+export * from "./compare-and-publish.js";

package/src/errors.ts

@@ -0,0 +1,137 @@
+import os from "node:os";
+
+import {
+  ACCESS_PUBLIC,
+  ACCESS_RESTRICTED,
+  STRATEGY_ALL,
+  STRATEGY_UPGRADE,
+} from "./options.js";
+
+export class InvalidPackageError extends TypeError {
+  public constructor(value: unknown) {
+    super(
+      `Package must be a directory, package.json, or .tgz file, got "${String(
+        value
+      )}"`
+    );
+    this.name = "PackageJsonReadError";
+  }
+}
+
+export class PackageJsonReadError extends Error {
+  public constructor(manifestPath: string, originalError: unknown) {
+    const message = [
+      `Could not read package.json at ${manifestPath}`,
+      originalError instanceof Error ? originalError.message : "",
+    ]
+      .filter(Boolean)
+      .join(os.EOL);
+
+    super(message);
+    this.name = "PackageJsonReadError";
+  }
+}
+
+export class PackageTarballReadError extends Error {
+  public constructor(tarballPath: string, originalError: unknown) {
+    const message = [
+      `Could not read package.json from ${tarballPath}`,
+      originalError instanceof Error ? originalError.message : "",
+    ]
+      .filter(Boolean)
+      .join(os.EOL);
+
+    super(message);
+    this.name = "PackageTarballReadError";
+  }
+}
+
+export class PackageJsonParseError extends SyntaxError {
+  public constructor(packageSpec: string, originalError: unknown) {
+    const message = [
+      `Invalid JSON, could not parse package.json for ${packageSpec}`,
+      originalError instanceof Error ? originalError.message : "",
+    ]
+      .filter(Boolean)
+      .join(os.EOL);
+
+    super(message);
+    this.name = "PackageJsonParseError";
+  }
+}
+
+export class InvalidPackageNameError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Package name must be a string, got "${String(value)}"`);
+    this.name = "InvalidPackageNameError";
+  }
+}
+
+export class InvalidPackageVersionError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Package version must be a string, got "${String(value)}"`);
+    this.name = "InvalidPackageVersionError";
+  }
+}
+
+export class InvalidPackagePublishConfigError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Publish config must be an object, got "${String(value)}"`);
+    this.name = "InvalidPackagePublishConfigError";
+  }
+}
+
+export class InvalidRegistryUrlError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Registry URL invalid, got "${String(value)}"`);
+    this.name = "InvalidRegistryUrlError";
+  }
+}
+
+export class InvalidTokenError extends TypeError {
+  public constructor() {
+    super("Token must be a non-empty string.");
+    this.name = "InvalidTokenError";
+  }
+}
+
+export class InvalidTagError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Tag must be a non-empty string, got "${String(value)}".`);
+    this.name = "InvalidTagError";
+  }
+}
+
+export class InvalidAccessError extends TypeError {
+  public constructor(value: unknown) {
+    super(
+      `Access must be "${ACCESS_PUBLIC}" or "${ACCESS_RESTRICTED}", got "${String(
+        value
+      )}".`
+    );
+    this.name = "InvalidAccessError";
+  }
+}
+
+export class InvalidStrategyError extends TypeError {
+  public constructor(value: unknown) {
+    super(
+      `Strategy must be "${STRATEGY_UPGRADE}" or "${STRATEGY_ALL}", got "${String(
+        value
+      )}".`
+    );
+    this.name = "InvalidStrategyError";
+  }
+}
+
+export class NpmCallError extends Error {
+  public constructor(command: string, exitCode: number, stderr: string) {
+    super(
+      [
+        `Call to "npm ${command}" exited with non-zero exit code ${exitCode}`,
+        stderr,
+      ].join(os.EOL)
+    );
+    this.name = "NpmCallError";
+  }
+}

package/src/format-publish-result.ts

@@ -0,0 +1,40 @@
+import os from "node:os";
+
+import type { PublishResult } from "./compare-and-publish/index.js";
+import type { PackageManifest } from "./read-manifest.js";
+import type { NormalizedOptions } from "./normalize-options.js";
+
+/**
+ * Format publish results into a string.
+ *
+ * @param manifest Package manifest
+ * @param options Configuration options.
+ * @param result Results from running npm publish.
+ * @returns Formatted string.
+ */
+export function formatPublishResult(
+  manifest: PackageManifest,
+  options: NormalizedOptions,
+  result: PublishResult
+): string {
+  if (result.id === undefined) {
+    return `🙅‍♀️ ${manifest.name}@${manifest.version} publish skipped.`;
+  }
+
+  return [
+    `📦 ${result.id}${options.dryRun.value ? " (DRY RUN)" : ""}`,
+    "=== Contents ===",
+    ...result.files.map(({ path, size }) => `${formatSize(size)}\t${path}`),
+  ].join(os.EOL);
+}
+
+const formatSize = (size: number): string => {
+  if (size < 1000) {
+    return `${size} B`;
+  }
+  if (size < 1_000_000) {
+    return `${(size / 1000).toFixed(1)} kB`;
+  }
+
+  return `${(size / 1_000_000).toFixed(1)} MB`;
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+// Export the external type definitions as named exports
+export * from "./options.js";
+export * from "./results.js";
+export * from "./errors.js";
+
+// Export `npmPublish` as a named export and the default export
+export { npmPublish } from "./npm-publish.js";

package/src/normalize-options.ts

@@ -0,0 +1,123 @@
+import os from "node:os";
+
+import * as errors from "./errors.js";
+import type { PackageManifest } from "./read-manifest.js";
+import {
+  ACCESS_PUBLIC,
+  ACCESS_RESTRICTED,
+  STRATEGY_UPGRADE,
+  STRATEGY_ALL,
+  type Access,
+  type Strategy,
+  type Options,
+  type Logger,
+} from "./options.js";
+
+const REGISTRY_NPM = "https://registry.npmjs.org/";
+export const TAG_LATEST = "latest";
+
+/** Normalized and sanitized auth, publish, and runtime configurations. */
+export interface NormalizedOptions {
+  registry: URL;
+  token: string;
+  tag: ConfigValue<string>;
+  access: ConfigValue<Access | undefined>;
+  provenance: ConfigValue<boolean>;
+  dryRun: ConfigValue<boolean>;
+  strategy: ConfigValue<Strategy>;
+  logger: Logger | undefined;
+  temporaryDirectory: string;
+}
+
+/** A config value, and whether that value differs from default. */
+export interface ConfigValue<TValue> {
+  value: TValue;
+  isDefault: boolean;
+}
+
+/**
+ * Normalizes and sanitizes options, and fills-in any default values.
+ *
+ * @param manifest Package metadata from package.json.
+ * @param options User-input options.
+ * @returns Validated auth and publish configuration.
+ */
+export function normalizeOptions(
+  manifest: PackageManifest,
+  options: Options
+): NormalizedOptions {
+  const defaultTag = manifest.publishConfig?.tag ?? TAG_LATEST;
+
+  const defaultRegistry = manifest.publishConfig?.registry ?? REGISTRY_NPM;
+
+  const defaultAccess =
+    manifest.publishConfig?.access ??
+    (manifest.scope === undefined ? ACCESS_PUBLIC : undefined);
+
+  const defaultProvenance = manifest.publishConfig?.provenance ?? false;
+
+  return {
+    token: validateToken(options.token),
+    registry: validateRegistry(options.registry ?? defaultRegistry),
+    tag: setValue(options.tag, defaultTag, validateTag),
+    access: setValue(options.access, defaultAccess, validateAccess),
+    provenance: setValue(options.provenance, defaultProvenance, Boolean),
+    dryRun: setValue(options.dryRun, false, Boolean),
+    strategy: setValue(options.strategy, STRATEGY_ALL, validateStrategy),
+    logger: options.logger,
+    temporaryDirectory: options.temporaryDirectory ?? os.tmpdir(),
+  };
+}
+
+const setValue = <TValue>(
+  value: unknown,
+  defaultValue: unknown,
+  validate: (value: unknown) => TValue
+): ConfigValue<TValue> => ({
+  value: validate(value ?? defaultValue),
+  isDefault: value === undefined,
+});
+
+const validateToken = (value: unknown): string => {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+
+  throw new errors.InvalidTokenError();
+};
+
+const validateRegistry = (value: unknown): URL => {
+  try {
+    return new URL(value as string | URL);
+  } catch {
+    throw new errors.InvalidRegistryUrlError(value);
+  }
+};
+
+const validateTag = (value: unknown): string => {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+
+  throw new errors.InvalidTagError(value);
+};
+
+const validateAccess = (value: unknown): Access | undefined => {
+  if (
+    value === undefined ||
+    value === ACCESS_PUBLIC ||
+    value === ACCESS_RESTRICTED
+  ) {
+    return value;
+  }
+
+  throw new errors.InvalidAccessError(value);
+};
+
+const validateStrategy = (value: unknown): Strategy => {
+  if (value === STRATEGY_ALL || value === STRATEGY_UPGRADE) {
+    return value;
+  }
+
+  throw new errors.InvalidStrategyError(value);
+};