@ebowwa/npm-publishing 1.0.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ebowwa/npm-publishing",
+  "version": "1.0.0",
+  "description": "NPM package publishing, version management, and validation utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "bun run --watch src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "semver": "^7.6.0",
+    "tar": "^7.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "@types/semver": "^7.5.0",
+    "@types/tar": "^6.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "npm",
+    "publish",
+    "semver",
+    "registry",
+    "version",
+    "validation"
+  ],
+  "author": "ebowwa",
+  "license": "MIT"
+}

package/src/bump-version.ts

@@ -0,0 +1,71 @@
+/**
+ * Bump the version in package.json
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import semver from 'semver';
+import type { BumpVersionOptions, BumpVersionResult } from './types.js';
+
+export async function bumpVersion(options: BumpVersionOptions): Promise<BumpVersionResult> {
+  try {
+    const packagePath = options.packagePath || process.cwd();
+    const packageJsonPath = join(packagePath, 'package.json');
+
+    if (!existsSync(packageJsonPath)) {
+      return {
+        success: false,
+        oldVersion: '',
+        newVersion: '',
+        error: `package.json not found at ${packageJsonPath}`,
+      };
+    }
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const oldVersion = packageJson.version || '0.0.0';
+
+    // Bump version using semver
+    let newVersion: string;
+    if (options.releaseType === 'prerelease') {
+      newVersion = options.preId
+        ? semver.inc(oldVersion, 'prerelease', options.preId) || oldVersion
+        : semver.inc(oldVersion, 'prerelease') || oldVersion;
+    } else if (options.releaseType.startsWith('pre')) {
+      if (options.preId) {
+        newVersion = semver.inc(oldVersion, options.releaseType as semver.ReleaseType, options.preId) || oldVersion;
+      } else {
+        newVersion = semver.inc(oldVersion, options.releaseType as semver.ReleaseType) || oldVersion;
+      }
+    } else {
+      newVersion = semver.inc(oldVersion, options.releaseType as semver.ReleaseType) || oldVersion;
+    }
+
+    // Update package.json
+    packageJson.version = newVersion;
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+    // Run npm version to update package-lock.json if present
+    try {
+      execSync(`npm version ${newVersion} --no-git-tag-version`, {
+        cwd: packagePath,
+        stdio: 'ignore',
+      });
+    } catch {
+      // Ignore if npm version fails
+    }
+
+    return {
+      success: true,
+      oldVersion,
+      newVersion,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      oldVersion: '',
+      newVersion: '',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/dist-tags.ts

@@ -0,0 +1,67 @@
+/**
+ * NPM dist-tag operations
+ */
+
+import { execSync } from 'child_process';
+import type { DistTagResult, DistTagsResult } from './types.js';
+
+export async function setDistTag(options: {
+  authToken: string;
+  packageName: string;
+  tag: string;
+  version: string;
+  registry?: string;
+}): Promise<DistTagResult> {
+  try {
+    const args = ['npm', 'dist-tag', 'add', `${options.packageName}@${options.version}`, options.tag];
+
+    if (options.registry) {
+      args.push('--registry', options.registry);
+    }
+
+    execSync(args.join(' '), {
+      env: { ...process.env, NPM_TOKEN: options.authToken },
+      stdio: 'pipe',
+    });
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function getDistTags(
+  packageName: string,
+  authToken: string,
+  registry?: string
+): Promise<DistTagsResult> {
+  try {
+    const args = ['npm', 'dist-tag', 'ls', packageName];
+
+    if (registry) {
+      args.push('--registry', registry);
+    }
+
+    const output = execSync(args.join(' '), {
+      env: { ...process.env, NPM_TOKEN: authToken },
+      encoding: 'utf-8',
+    });
+
+    // Parse output: "latest: 1.0.0\nbeta: 1.1.0"
+    const tags: Record<string, string> = {};
+    for (const line of output.trim().split('\n')) {
+      const [tag, version] = line.split(':').map((s) => s.trim());
+      tags[tag] = version;
+    }
+
+    return { success: true, tags };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/fetch-tarball.ts

@@ -0,0 +1,104 @@
+/**
+ * Download and extract source files from a published npm package tarball
+ */
+
+import { Readable } from 'stream';
+import { createWriteStream } from 'fs';
+import { join } from 'path';
+import { pipeline } from 'stream/promises';
+import * as tar from 'tar';
+import { unlink } from 'fs/promises';
+import type { TarballResult, PackageFile } from './types.js';
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+export async function fetchPackageTarball(
+  packageName: string,
+  version?: string,
+  registry?: string
+): Promise<TarballResult> {
+  const tempDir = '/tmp';
+  const tempFile = join(tempDir, `${packageName}-${version || 'latest'}.tgz`);
+
+  try {
+    // Get package metadata to find tarball URL
+    const registryUrl = registry || DEFAULT_REGISTRY;
+    const packageUrl = `${registryUrl}/${packageName}`;
+    const response = await fetch(packageUrl);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch package metadata: ${response.status}`);
+    }
+
+    const metadata = await response.json();
+    const resolvedVersion = version || metadata['dist-tags'].latest;
+    const tarballUrl = metadata.versions[resolvedVersion].dist.tarball;
+
+    // Download tarball
+    const tarballResponse = await fetch(tarballUrl);
+    if (!tarballResponse.ok) {
+      throw new Error(`Failed to download tarball: ${tarballResponse.status}`);
+    }
+
+    // Write tarball to temp file
+    const writeStream = createWriteStream(tempFile);
+    await pipeline(Readable.fromWeb(tarballResponse.body as any), writeStream);
+
+    // Extract tarball
+    const files: PackageFile[] = [];
+    const extractPath = join(tempDir, `${packageName}-${Date.now()}`);
+
+    await tar.extract({
+      file: tempFile,
+      cwd: extractPath,
+      strip: 1, // Remove the 'package/' prefix
+    });
+
+    // Read extracted files
+    const { readdirSync, readFileSync, statSync } = await import('fs');
+    const { join: joinPath } = await import('path');
+
+    function readDirRecursive(dir: string, basePath = ''): PackageFile[] {
+      const result: PackageFile[] = [];
+      const entries = readdirSync(dir);
+
+      for (const entry of entries) {
+        const fullPath = joinPath(dir, entry);
+        const relativePath = basePath ? joinPath(basePath, entry) : entry;
+        const stat = statSync(fullPath);
+
+        if (stat.isDirectory()) {
+          result.push(...readDirRecursive(fullPath, relativePath));
+        } else if (stat.isFile()) {
+          try {
+            const content = readFileSync(fullPath, 'utf-8');
+            result.push({ path: relativePath, content });
+          } catch {
+            // Skip files that can't be read as text
+          }
+        }
+      }
+
+      return result;
+    }
+
+    files.push(...readDirRecursive(extractPath));
+
+    // Clean up temp file
+    await unlink(tempFile).catch(() => {});
+
+    return {
+      success: true,
+      version: resolvedVersion,
+      files,
+    };
+  } catch (error) {
+    // Clean up temp file on error
+    unlink(tempFile).catch(() => {});
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * NPM Publishing Library
+ *
+ * Utilities for NPM package publishing, version management,
+ * validation, search, and dist-tag operations.
+ */
+
+// Export all functions and types
+export * from './publish.js';
+export * from './bump-version.js';
+export * from './validate.js';
+export * from './dist-tags.js';
+export * from './search.js';
+export * from './package-details.js';
+export * from './read-files.js';
+export * from './fetch-tarball.js';
+export * from './types.js';

package/src/package-details.ts

@@ -0,0 +1,19 @@
+/**
+ * Get detailed information about an npm package
+ */
+
+import type { PackageDetails } from './types.js';
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+export async function getPackageDetails(name: string): Promise<PackageDetails> {
+  const url = `${DEFAULT_REGISTRY}/${name}`;
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch package details: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return data;
+}

package/src/publish.ts

@@ -0,0 +1,64 @@
+/**
+ * Publish a package to the npm registry
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import type { PublishOptions, PublishResult } from './types.js';
+
+export async function publish(options: PublishOptions): Promise<PublishResult> {
+  try {
+    const packagePath = options.packagePath || process.cwd();
+    const packageJsonPath = join(packagePath, 'package.json');
+
+    if (!existsSync(packageJsonPath)) {
+      return {
+        success: false,
+        error: `package.json not found at ${packageJsonPath}`,
+      };
+    }
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const { name, version } = packageJson;
+
+    // Set npm token for this session
+    process.env.NPM_TOKEN = options.authToken;
+
+    const args = ['publish'];
+
+    if (options.dryRun) {
+      args.push('--dry-run');
+    }
+
+    if (options.registry) {
+      args.push('--registry', options.registry);
+    }
+
+    if (options.tag) {
+      args.push('--tag', options.tag);
+    }
+
+    if (options.access) {
+      args.push('--access', options.access);
+    }
+
+    // Execute npm publish
+    const output = execSync(`npm ${args.join(' ')}`, {
+      cwd: packagePath,
+      env: { ...process.env, NPM_TOKEN: options.authToken },
+      encoding: 'utf-8',
+    });
+
+    return {
+      success: true,
+      name,
+      version,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/read-files.ts

@@ -0,0 +1,79 @@
+/**
+ * Read source files from a local package directory
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import type { ReadFilesResult } from './types.js';
+
+export async function readPackageFiles(packagePath?: string): Promise<ReadFilesResult> {
+  try {
+    const path = packagePath || process.cwd();
+    const packageJsonPath = join(path, 'package.json');
+
+    if (!existsSync(packageJsonPath)) {
+      return {
+        success: false,
+        error: `package.json not found at ${packageJsonPath}`,
+      };
+    }
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const filesField = packageJson.files || [];
+
+    // Determine which files to read
+    const filesToRead: string[] = [];
+
+    if (filesField.length > 0) {
+      // Use files field as filter
+      for (const pattern of filesField) {
+        if (pattern.includes('*')) {
+          // Wildcard patterns - simplified handling
+          const ext = pattern.split('*')[1] || '';
+          const jsFiles = ['index.js', 'index.ts', 'src/index.ts', 'dist/index.js'];
+          for (const file of jsFiles) {
+            if (file.endsWith(ext.replace(/^\./, ''))) {
+              filesToRead.push(file);
+            }
+          }
+        } else {
+          filesToRead.push(pattern);
+        }
+      }
+    } else {
+      // Default: read package.json and common source files
+      filesToRead.push('package.json', 'README.md', 'index.js', 'index.ts', 'src/index.ts');
+    }
+
+    const files = [];
+    let errorCount = 0;
+
+    for (const file of filesToRead) {
+      const filePath = join(path, file);
+      if (existsSync(filePath)) {
+        try {
+          const content = readFileSync(filePath, 'utf-8');
+          files.push({ path: file, content });
+        } catch {
+          errorCount++;
+        }
+      }
+    }
+
+    const result: ReadFilesResult = {
+      success: true,
+      files,
+    };
+
+    if (errorCount > 0) {
+      result.error = `Failed to read ${errorCount} file(s)`;
+    }
+
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/search.ts

@@ -0,0 +1,48 @@
+/**
+ * Search for packages on the npm registry
+ */
+
+import type { SearchOptions, SearchResult } from './types.js';
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+export async function search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
+  const limit = options.limit || 250;
+  const results: SearchResult[] = [];
+
+  try {
+    const url = `${DEFAULT_REGISTRY}/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`npm registry returned ${response.status}`);
+    }
+
+    const data = await response.json();
+    const objects = data.objects || [];
+
+    for (const obj of objects) {
+      const pkg = obj.package;
+      results.push({
+        package: {
+          name: pkg.name,
+          version: pkg.version,
+          description: pkg.description,
+          keywords: pkg.keywords,
+        },
+        score: {
+          final: obj.score.final,
+          detail: obj.score.detail,
+        },
+        downloads: {
+          monthly: obj.downloads?.monthly || 0,
+        },
+      });
+    }
+
+    return results;
+  } catch (error) {
+    console.error('Search failed:', error);
+    return [];
+  }
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Type definitions for NPM publishing operations
+ */
+
+export interface PackageFile {
+  path: string;
+  content: string;
+}
+
+export interface PublishOptions {
+  authToken: string;
+  dryRun?: boolean;
+  packagePath?: string;
+  registry?: string;
+  tag?: string;
+  access?: "public" | "restricted";
+}
+
+export interface PublishResult {
+  success: boolean;
+  name?: string;
+  version?: string;
+  error?: string;
+}
+
+export interface BumpVersionOptions {
+  releaseType: "major" | "minor" | "patch" | "premajor" | "preminor" | "prepatch" | "prerelease";
+  packagePath?: string;
+  preId?: string;
+}
+
+export interface BumpVersionResult {
+  success: boolean;
+  oldVersion: string;
+  newVersion: string;
+  error?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface DistTagResult {
+  success: boolean;
+  error?: string;
+}
+
+export interface DistTagsResult {
+  success: boolean;
+  tags?: Record<string, string>;
+  error?: string;
+}
+
+export interface SearchOptions {
+  limit?: number;
+}
+
+export interface SearchResult {
+  package: {
+    name: string;
+    version: string;
+    description?: string;
+    keywords?: string[];
+  };
+  score: {
+    final: number;
+    detail: {
+      quality: number;
+      popularity: number;
+      maintenance: number;
+    };
+  };
+  downloads: {
+    monthly: number;
+  };
+}
+
+export interface PackageDetails {
+  name: string;
+  version: string;
+  description?: string;
+  license: string;
+  homepage?: string;
+  repository?: {
+    type: string;
+    url: string;
+  };
+  author?: string | {
+    name: string;
+  };
+  "dist-tags": Record<string, string>;
+  versions: Record<string, unknown>;
+  keywords?: string[];
+}
+
+export interface ReadFilesResult {
+  success: boolean;
+  files?: PackageFile[];
+  error?: string;
+}
+
+export interface TarballResult {
+  success: boolean;
+  version?: string;
+  files?: PackageFile[];
+  error?: string;
+}

package/src/validate.ts

@@ -0,0 +1,69 @@
+/**
+ * Validate package.json for npm publishing requirements
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import type { ValidationResult } from './types.js';
+
+export async function validatePackage(packagePath?: string): Promise<ValidationResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const path = packagePath || process.cwd();
+  const packageJsonPath = join(path, 'package.json');
+
+  if (!existsSync(packageJsonPath)) {
+    errors.push('package.json not found');
+    return { valid: false, errors, warnings };
+  }
+
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+  // Required fields
+  if (!packageJson.name) {
+    errors.push('Missing required field: name');
+  } else if (!/^[a-z0-9][a-z0-9-._]*$/.test(packageJson.name)) {
+    errors.push('Package name must be lowercase and can only contain letters, numbers, hyphens, underscores, and dots');
+  }
+
+  if (!packageJson.version) {
+    errors.push('Missing required field: version');
+  } else if (!/^\d+\.\d+\.\d+/.test(packageJson.version)) {
+    errors.push('Version must be a valid semver (e.g., 1.0.0)');
+  }
+
+  // Warnings for recommended fields
+  if (!packageJson.description) {
+    warnings.push('Missing recommended field: description');
+  }
+
+  if (!packageJson.author) {
+    warnings.push('Missing recommended field: author');
+  }
+
+  if (!packageJson.license) {
+    warnings.push('Missing recommended field: license');
+  }
+
+  if (!packageJson.keywords || packageJson.keywords.length === 0) {
+    warnings.push('Missing recommended field: keywords');
+  }
+
+  // Check for README
+  const readmeExists = existsSync(join(path, 'README.md')) || existsSync(join(path, 'README'));
+  if (!readmeExists) {
+    warnings.push('Missing README.md file');
+  }
+
+  // Validate files field if present
+  if (packageJson.files && !Array.isArray(packageJson.files)) {
+    errors.push('files field must be an array');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}