@jsdevtools/npm-publish 1.4.2 → 2.0.0

package/src/cli/index.ts

@@ -0,0 +1,69 @@
+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 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,48 @@
+/** 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: "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-versions.ts

@@ -0,0 +1,52 @@
+import {
+  valid as semverValid,
+  gt as semverGreaterThan,
+  diff as semverDifference,
+  type ReleaseType as SemverReleaseType,
+} from "semver";
+
+import { STRATEGY_ALL } from "./options.js";
+import type { NormalizedOptions } from "./normalize-options.js";
+import type { PublishedVersions } from "./npm/index.js";
+
+export type ReleaseType = SemverReleaseType | typeof INITIAL | typeof DIFFERENT;
+
+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 version 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(
+  version: string,
+  publishedVersions: PublishedVersions,
+  options: NormalizedOptions
+): VersionComparison {
+  const { versions: existingVersions, "dist-tags": tags } = publishedVersions;
+  const { strategy, tag: publishTag } = options;
+  const oldVersion = semverValid(tags[publishTag.value]) ?? undefined;
+  const isUnique = !existingVersions.includes(version);
+  let type: ReleaseType | undefined;
+
+  if (isUnique) {
+    if (!oldVersion) {
+      type = INITIAL;
+    } else if (semverGreaterThan(version, oldVersion)) {
+      type = semverDifference(version, oldVersion) ?? DIFFERENT;
+    } else if (strategy.value === STRATEGY_ALL) {
+      type = DIFFERENT;
+    }
+  }
+
+  return { type, oldVersion };
+}

package/src/errors.ts

@@ -0,0 +1,130 @@
+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 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 "./npm/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 results Results from running npm publish.
+ * @returns Formatted string.
+ */
+export function formatPublishResult(
+  manifest: PackageManifest,
+  options: NormalizedOptions,
+  results?: PublishResult
+): string {
+  if (results === undefined) {
+    return `🙅‍♀️ ${manifest.name}@${manifest.version} publish skipped.`;
+  }
+
+  return [
+    `📦 ${results.id}${options.dryRun.value ? " (DRY RUN)" : ""}`,
+    "=== Contents ===",
+    ...results.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,119 @@
+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 DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+const DEFAULT_TAG = "latest";
+
+/** Normalized and sanitized auth, publish, and runtime configurations. */
+export interface NormalizedOptions {
+  registry: URL;
+  token: string;
+  tag: ConfigValue<string>;
+  access: ConfigValue<Access | undefined>;
+  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 options User-input options.
+ * @param manifest Package metadata from package.json.
+ * @returns Validated auth and publish configuration.
+ */
+export function normalizeOptions(
+  options: Options,
+  manifest: PackageManifest
+): NormalizedOptions {
+  const defaultTag = manifest.publishConfig?.tag ?? DEFAULT_TAG;
+
+  const defaultRegistry = manifest.publishConfig?.registry ?? DEFAULT_REGISTRY;
+
+  const defaultAccess =
+    manifest.publishConfig?.access ??
+    (manifest.scope === undefined ? ACCESS_PUBLIC : undefined);
+
+  return {
+    token: validateToken(options.token),
+    registry: validateRegistry(options.registry ?? defaultRegistry),
+    tag: setValue(options.tag, defaultTag, validateTag),
+    access: setValue(options.access, defaultAccess, validateAccess),
+    dryRun: setValue(options.dryRun, false, validateDryRun),
+    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 => {
+  return value as string;
+};
+
+const validateDryRun = (value: unknown): boolean => {
+  return value as boolean;
+};
+
+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);
+};

package/src/npm/call-npm-cli.ts

@@ -0,0 +1,98 @@
+import childProcess from "node:child_process";
+import os from "node:os";
+
+import * as errors from "../errors.js";
+import type { Logger } from "../options.js";
+import type { NpmCliEnvironment } from "./use-npm-environment.js";
+
+export interface NpmCliOptions<TReturn> {
+  environment?: NpmCliEnvironment;
+  ifError?: Record<string, TReturn>;
+  logger?: Logger | undefined;
+}
+
+const NPM = os.platform() === "win32" ? "npm.cmd" : "npm";
+const JSON_MATCH_RE = /(\{[\s\S]*\})/mu;
+
+const execNpm = (
+  commandArguments: string[],
+  environment: Record<string, string> = {},
+  logger?: Logger
+): Promise<{ stdout: string; stderr: string; exitCode: number }> => {
+  logger?.debug?.(`Running command: ${NPM} ${commandArguments.join(" ")}`);
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+
+    const npm = childProcess.spawn(NPM, commandArguments, {
+      env: { ...process.env, ...environment },
+    });
+
+    npm.stdout.on("data", (data) => (stdout += data));
+    npm.stderr.on("data", (data) => (stderr += data));
+    npm.on("close", (code) => {
+      resolve({
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 0,
+      });
+    });
+  });
+};
+
+const parseJson = <TParsed>(...values: string[]): TParsed | undefined => {
+  for (const value of values) {
+    const jsonValue = JSON_MATCH_RE.exec(value)?.[1];
+
+    if (jsonValue) {
+      try {
+        return JSON.parse(jsonValue) as TParsed;
+      } catch {
+        return undefined;
+      }
+    }
+  }
+
+  return undefined;
+};
+
+/**
+ * Call the NPM CLI in JSON mode.
+ *
+ * @param command The command of the NPM CLI to call
+ * @param cliArguments Any arguments to send to the command
+ * @param options Customize environment variables or add an error handler.
+ * @returns The parsed JSON, or stdout if unparsable.
+ */
+export async function callNpmCli<TReturn = string>(
+  command: string,
+  cliArguments: string[],
+  options: NpmCliOptions<TReturn> = {}
+): Promise<TReturn> {
+  const { stdout, stderr, exitCode } = await execNpm(
+    [command, "--ignore-scripts", "--json", ...cliArguments],
+    options.environment,
+    options.logger
+  );
+
+  if (exitCode !== 0) {
+    const errorPayload = parseJson<{ error?: { code?: string | null } }>(
+      stdout,
+      stderr
+    );
+    const errorCode = errorPayload?.error?.code?.toLowerCase();
+
+    if (
+      typeof errorCode === "string" &&
+      options.ifError &&
+      errorCode in options.ifError
+    ) {
+      return options.ifError[errorCode] as TReturn;
+    }
+
+    throw new errors.NpmCallError(command, exitCode, stderr);
+  }
+
+  return parseJson(stdout) ?? (stdout as unknown as TReturn);
+}

package/src/npm/get-publish-arguments.ts

@@ -0,0 +1,34 @@
+import type { NormalizedOptions } from "../normalize-options.js";
+
+/**
+ * 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 } = 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 (dryRun.value) {
+    publishArguments.push("--dry-run");
+  }
+
+  return publishArguments;
+}

package/src/npm/index.ts

@@ -0,0 +1,64 @@
+import type { NormalizedOptions } from "../normalize-options.js";
+import { useNpmEnvironment } from "./use-npm-environment.js";
+import { callNpmCli } from "./call-npm-cli.js";
+import { getPublishArguments } from "./get-publish-arguments.js";
+
+export interface PublishedVersions {
+  "dist-tags": Record<string, string>;
+  versions: string[];
+}
+
+export interface PublishFile {
+  path: string;
+  size: number;
+}
+
+export interface PublishResult {
+  id: string;
+  files: PublishFile[];
+}
+
+/**
+ * Get a package's published versions.
+ *
+ * @param packageName The name of the package to get published versions for.
+ * @param options Configuration options.
+ * @returns All published versions and tags.
+ */
+export async function getVersions(
+  packageName: string,
+  options: NormalizedOptions
+): Promise<PublishedVersions> {
+  return useNpmEnvironment(options, (environment) => {
+    return callNpmCli<PublishedVersions>(
+      "view",
+      [packageName, "dist-tags", "versions"],
+      {
+        logger: options.logger,
+        environment,
+        ifError: { e404: { "dist-tags": {}, versions: [] } },
+      }
+    );
+  });
+}
+
+/**
+ * Publish a package.
+ *
+ * @param packageSpec Package specification to pass to npm.
+ * @param options Configuration options.
+ * @returns Release metadata.
+ */
+export async function publish(
+  packageSpec: string,
+  options: NormalizedOptions
+): Promise<PublishResult> {
+  const publishArguments = getPublishArguments(packageSpec, options);
+
+  return useNpmEnvironment(options, (environment) => {
+    return callNpmCli<PublishResult>("publish", publishArguments, {
+      logger: options.logger,
+      environment,
+    });
+  });
+}