create-svc 0.1.79 → 0.1.80

package/README.md

@@ -17,6 +17,36 @@ Local provisioning intentionally prefers known-good CLIs over SDK-heavy orchestr
 
 npm: <https://www.npmjs.com/package/create-svc>
 
+## Install and update
+
+For an installed CLI, use npm as the canonical owner:
+
+```bash
+npm install -g create-svc@latest
+```
+
+That installs the `service`, `create-svc`, and `create-service` commands from the same package. Check the binary that is actually running:
+
+```bash
+service --version
+service doctor
+```
+
+`service doctor` reports the active binary path, package root, installed package version, npm latest version, and any other `service` binaries on `PATH`. If a stale Homebrew or manually copied binary is shadowing npm, remove that stale binary and reinstall npm latest:
+
+```bash
+which -a service
+rm "/opt/homebrew/bin/service"
+npm install -g create-svc@latest
+```
+
+If the stale binary came from a global npm install you no longer want, remove and reinstall it through npm instead:
+
+```bash
+npm uninstall -g create-svc
+npm install -g create-svc@latest
+```
+
 ## Usage
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-svc",
-  "version": "0.1.79",
+  "version": "0.1.80",
   "description": "Local microservice bootstrap CLI for Cloud Run and Workers services with Neon-backed data.",
   "module": "index.ts",
   "type": "module",

package/src/service-diagnostics.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { buildServiceDoctorReport, findServiceBinaries } from "./service-diagnostics";
+
+test("findServiceBinaries finds service commands on a provided PATH", () => {
+  const binaries = findServiceBinaries({
+    pathEnv: ["/old/bin", "/fresh/bin", "/missing/bin"].join(":"),
+    isExecutable: (path) => path === "/old/bin/service" || path === "/fresh/bin/service",
+  });
+
+  expect(binaries).toEqual(["/old/bin/service", "/fresh/bin/service"]);
+});
+
+test("buildServiceDoctorReport includes the active binary, package root, and version", () => {
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: "/fresh/bin/service",
+    packageRoot: "/fresh/lib/node_modules/create-svc",
+    packageVersion: "0.1.77",
+    latestVersion: "0.1.77",
+    serviceBinaries: ["/fresh/bin/service"],
+    getBinaryVersion: () => "0.1.77",
+  });
+
+  expect(report.exitCode).toBe(0);
+  expect(report.text).toContain("active binary: /fresh/bin/service");
+  expect(report.text).toContain("package root: /fresh/lib/node_modules/create-svc");
+  expect(report.text).toContain("package version: 0.1.77");
+  expect(report.text).toContain("npm latest: 0.1.77");
+});
+
+test("buildServiceDoctorReport warns when stale service binaries are also on PATH", () => {
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: "/fresh/bin/service",
+    packageRoot: "/fresh/lib/node_modules/create-svc",
+    packageVersion: "0.1.77",
+    latestVersion: "0.1.77",
+    serviceBinaries: ["/opt/homebrew/bin/service", "/fresh/bin/service"],
+    getBinaryVersion: (path) => (path === "/opt/homebrew/bin/service" ? "0.1.10" : "0.1.77"),
+  });
+
+  expect(report.exitCode).toBe(1);
+  expect(report.text).toContain("warning: multiple service binaries found on PATH");
+  expect(report.text).toContain("/opt/homebrew/bin/service");
+  expect(report.text).toContain("version: 0.1.10 (stale)");
+  expect(report.text).toContain('cleanup: rm "/opt/homebrew/bin/service"');
+  expect(report.text).toContain("update: npm install -g create-svc@latest");
+});

package/src/service-diagnostics.ts

@@ -0,0 +1,170 @@
+import { accessSync, constants, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type FindServiceBinariesOptions = {
+  pathEnv?: string;
+  commandName?: string;
+  isExecutable?: (path: string) => boolean;
+};
+
+type BuildServiceDoctorReportOptions = {
+  activeBinaryPath: string;
+  packageRoot: string;
+  packageVersion: string;
+  latestVersion?: string;
+  latestVersionError?: string;
+  serviceBinaries: string[];
+  getBinaryVersion: (path: string) => string | undefined;
+};
+
+type DoctorReport = {
+  exitCode: number;
+  text: string;
+};
+
+const PACKAGE_NAME = "create-svc";
+const SERVICE_COMMAND = "service";
+
+export function packageRootFromModuleUrl(moduleUrl: string) {
+  return resolve(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+export function readPackageVersion(packageRoot: string) {
+  const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version?: string };
+  return packageJson.version ?? "unknown";
+}
+
+export function findServiceBinaries(options: FindServiceBinariesOptions = {}) {
+  const commandName = options.commandName ?? SERVICE_COMMAND;
+  const isExecutable = options.isExecutable ?? defaultIsExecutable;
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  for (const entry of (options.pathEnv ?? process.env.PATH ?? "").split(":")) {
+    if (!entry) {
+      continue;
+    }
+
+    const candidate = join(entry, commandName);
+    if (seen.has(candidate)) {
+      continue;
+    }
+    seen.add(candidate);
+
+    if (isExecutable(candidate)) {
+      results.push(candidate);
+    }
+  }
+
+  return results;
+}
+
+export function buildServiceDoctorReport(options: BuildServiceDoctorReportOptions): DoctorReport {
+  const lines = [
+    "service doctor",
+    `active binary: ${options.activeBinaryPath}`,
+    `package root: ${options.packageRoot}`,
+    `package version: ${options.packageVersion}`,
+  ];
+
+  if (options.latestVersion) {
+    lines.push(`npm latest: ${options.latestVersion}`);
+  } else if (options.latestVersionError) {
+    lines.push(`npm latest: unavailable (${options.latestVersionError})`);
+  } else {
+    lines.push("npm latest: unavailable");
+  }
+
+  const binaries = uniquePaths(options.serviceBinaries);
+  const binaryDiagnostics = binaries.map((path) => {
+    const version = options.getBinaryVersion(path);
+    const stale = Boolean(version && options.latestVersion && compareVersions(version, options.latestVersion) < 0);
+    return { path, version, stale };
+  });
+
+  const staleBinaries = binaryDiagnostics.filter((binary) => binary.stale);
+  if (binaryDiagnostics.length > 1) {
+    lines.push("");
+    lines.push("warning: multiple service binaries found on PATH");
+    for (const binary of binaryDiagnostics) {
+      const version = binary.version ?? "unknown";
+      const state = binary.stale ? "stale" : binary.version && options.latestVersion ? "current" : "unknown";
+      lines.push(`- ${binary.path}`);
+      lines.push(`  version: ${version} (${state})`);
+      if (binary.stale) {
+        lines.push(`  cleanup: rm "${binary.path}"`);
+        lines.push(`  update: npm install -g ${PACKAGE_NAME}@latest`);
+      }
+    }
+  }
+
+  return {
+    exitCode: staleBinaries.length > 0 ? 1 : 0,
+    text: lines.join("\n"),
+  };
+}
+
+export function getInstalledServiceVersion(binaryPath: string) {
+  const result = safeSpawn([binaryPath, "--version"]);
+
+  if (!result || !result.success || !result.stdout) {
+    return undefined;
+  }
+
+  return new TextDecoder().decode(result.stdout).trim().match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0];
+}
+
+export function getNpmLatestVersion() {
+  const result = safeSpawn(["npm", "view", `${PACKAGE_NAME}@latest`, "version"]);
+
+  if (!result || !result.success || !result.stdout) {
+    const stderr = result?.stderr ? new TextDecoder().decode(result.stderr).trim() : "npm view failed";
+    return { error: stderr || "npm view failed" };
+  }
+
+  return { version: new TextDecoder().decode(result.stdout).trim() };
+}
+
+function safeSpawn(command: string[]) {
+  try {
+    return Bun.spawnSync(command, {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+export function compareVersions(left: string, right: string) {
+  const leftParts = parseVersion(left);
+  const rightParts = parseVersion(right);
+
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (leftParts[i] ?? 0) - (rightParts[i] ?? 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+
+  return 0;
+}
+
+function parseVersion(version: string): [number, number, number] {
+  const [major = "0", minor = "0", patch = "0"] = version.split(/[.-]/, 3);
+  return [Number(major) || 0, Number(minor) || 0, Number(patch) || 0];
+}
+
+function uniquePaths(paths: string[]) {
+  return [...new Set(paths)];
+}
+
+function defaultIsExecutable(path: string) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/service.ts

@@ -3,6 +3,13 @@ import { dirname, join } from "node:path";
 import { formatScaffoldHelp, run as runScaffoldCli } from "./cli";
 import { parseProtectMainArgs, protectMainBranch } from "./github-protection";
 import { parseJsonc } from "./jsonc";
+import {
+  buildServiceDoctorReport,
+  findServiceBinaries,
+  getInstalledServiceVersion,
+  getNpmLatestVersion,
+  packageRootFromModuleUrl,
+} from "./service-diagnostics";
 
 const SCAFFOLD_COMMANDS = new Set(["create", "new", "init"]);
 const GENERATED_SERVICE_COMMANDS = new Set([
@@ -43,6 +50,11 @@ export async function runServiceCommand(argv: string[], cwd = process.cwd()) {
     return;
   }
 
+  if (command === "doctor") {
+    runGlobalServiceDoctor();
+    return;
+  }
+
   console.error(formatOutsideServiceCommandError(command));
   process.exit(1);
 }
@@ -56,6 +68,23 @@ export function createSvcVersion() {
   return packageJson.version || "unknown";
 }
 
+function runGlobalServiceDoctor() {
+  const latest = getNpmLatestVersion();
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: process.argv[1] || "service",
+    packageRoot: packageRootFromModuleUrl(import.meta.url),
+    packageVersion: createSvcVersion(),
+    latestVersion: latest.version,
+    latestVersionError: latest.error,
+    serviceBinaries: findServiceBinaries(),
+    getBinaryVersion: getInstalledServiceVersion,
+  });
+  console.log(report.text);
+  if (report.exitCode !== 0) {
+    process.exit(report.exitCode);
+  }
+}
+
 export function normalizeScaffoldArgs(argv: string[]) {
   const [command, ...rest] = argv;
   if (command && SCAFFOLD_COMMANDS.has(command)) {