create-checkstack-plugin 0.1.0

package/src/local-registry.ts

@@ -0,0 +1,313 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+/** The package.json fields this harness reads. Unknown keys are ignored. */
+const packageJsonSchema = z.object({
+  name: z.string().optional(),
+  version: z.string().optional(),
+  private: z.boolean().optional(),
+});
+
+/** Read + zod-parse a package.json, returning the fields we care about. */
+function readPackageJson(pkgPath: string): z.infer<typeof packageJsonSchema> {
+  return packageJsonSchema.parse(
+    JSON.parse(fs.readFileSync(pkgPath, "utf8")) as unknown,
+  );
+}
+
+/**
+ * Local-registry publish harness for the external-plugin lifecycle
+ * integration test (#251 Phase 3).
+ *
+ * The published-tarball path is what the integration test guards, so it
+ * needs a real registry serving the *current* working tree's
+ * `@checkstack/*` packages — not whatever is live on npm. We spin up a
+ * throwaway [Verdaccio](https://verdaccio.org/) on `localhost`, publish
+ * every non-private workspace package into it, and point the scaffolder +
+ * `bun install` at it.
+ *
+ * Publish-protocol caveat (plan §7.2 step 1.3): `scripts/publish-packages.ts`
+ * publishes to the REAL npm registry via `bun publish` and skips
+ * already-published versions, so it is not directly reusable here. We use
+ * the plan's preferred default (a): `bun publish --registry <localUrl>` per
+ * package. `bun publish` (unlike `npm publish`) resolves `workspace:*` to
+ * concrete versions at pack time — the same reason `publish-packages.ts`
+ * uses it — so the published tarballs install cleanly outside the monorepo.
+ *
+ * Everything network/process-touching is injectable so the pure builders
+ * (config, `.npmrc`, arg vectors) stay unit-testable without spawning
+ * anything.
+ */
+
+/** Default host:port the throwaway Verdaccio listens on. */
+export const DEFAULT_REGISTRY_PORT = 4873;
+export const DEFAULT_REGISTRY_URL = `http://localhost:${DEFAULT_REGISTRY_PORT}`;
+
+/**
+ * Build a Verdaccio `config.yaml` that allows anonymous publish for the
+ * scope(s) the test publishes, with auth disabled (a throwaway token still
+ * satisfies the publish protocol — see {@link buildNpmrc}). Uglify/web UI
+ * are off to keep the boot fast.
+ */
+export function buildVerdaccioConfig({
+  storageDir,
+  port = DEFAULT_REGISTRY_PORT,
+}: {
+  storageDir: string;
+  port?: number;
+}): string {
+  // Anonymous publish is intentional: this registry is ephemeral, bound to
+  // localhost, and never persists past the test. `$all` / `$anonymous`
+  // groups let the publish step skip a real login flow.
+  return [
+    `storage: ${JSON.stringify(storageDir)}`,
+    "uplinks:",
+    "  npmjs:",
+    "    url: https://registry.npmjs.org/",
+    "packages:",
+    "  '@checkstack/*':",
+    "    access: $all",
+    "    publish: $anonymous",
+    "    unpublish: $anonymous",
+    "  'create-checkstack-plugin':",
+    "    access: $all",
+    "    publish: $anonymous",
+    "    unpublish: $anonymous",
+    // Everything else proxies to the public registry so transitive
+    // third-party deps (drizzle-orm, @orpc/*, vite, ...) still resolve.
+    "  '**':",
+    "    access: $all",
+    "    publish: $anonymous",
+    "    proxy: npmjs",
+    "log: { type: stdout, format: pretty, level: warn }",
+    `listen: 0.0.0.0:${port}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Build a throwaway `.npmrc` that (a) pins the `@checkstack` scope +
+ * `create-checkstack-plugin` fetches to the local registry and (b) carries
+ * a fake `_authToken` so the publish protocol is satisfied even though the
+ * registry accepts anonymous writes.
+ */
+export function buildNpmrc({
+  registryUrl = DEFAULT_REGISTRY_URL,
+}: {
+  registryUrl?: string;
+} = {}): string {
+  const hostPath = registryUrl.replace(/^https?:/, "");
+  return [
+    `registry=${registryUrl}`,
+    `@checkstack:registry=${registryUrl}`,
+    `${hostPath}/:_authToken=fake-checkstack-it-token`,
+    "always-auth=false",
+    "",
+  ].join("\n");
+}
+
+/** Build the `bun publish` argv for one package dir against the local registry. */
+export function buildBunPublishArgs({
+  registryUrl = DEFAULT_REGISTRY_URL,
+}: {
+  registryUrl?: string;
+} = {}): string[] {
+  // `--access public` mirrors publish-packages.ts; `--no-git-checks` is not
+  // a bun flag, so we simply publish from the package dir. bun resolves
+  // workspace:* to concrete versions automatically.
+  return ["publish", "--registry", registryUrl, "--access", "public"];
+}
+
+/** Build the `npm view <pkg> version` argv against the local registry. */
+export function buildNpmViewVersionArgs({
+  packageName,
+  registryUrl = DEFAULT_REGISTRY_URL,
+}: {
+  packageName: string;
+  registryUrl?: string;
+}): string[] {
+  return ["view", `${packageName}`, "version", "--registry", registryUrl];
+}
+
+/** A workspace package the harness publishes. */
+export interface WorkspacePackage {
+  name: string;
+  version: string;
+  dir: string;
+  private: boolean;
+}
+
+/**
+ * Discover every publishable workspace package (`core/*`, `plugins/*`),
+ * skipping `private: true` and `_`-prefixed scaffold/test dirs. We publish
+ * the FULL set rather than a hand-maintained ~11 because the scaffolded
+ * plugin depends on `@checkstack/backend`, whose transitive closure spans
+ * most of the platform — a partial list would break `bun install`.
+ */
+export function discoverWorkspacePackages({
+  monorepoRoot,
+}: {
+  monorepoRoot: string;
+}): WorkspacePackage[] {
+  const packages: WorkspacePackage[] = [];
+  for (const wsDir of ["core", "plugins"]) {
+    const wsPath = path.join(monorepoRoot, wsDir);
+    if (!fs.existsSync(wsPath)) continue;
+    for (const entry of fs.readdirSync(wsPath, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
+      const pkgPath = path.join(wsPath, entry.name, "package.json");
+      if (!fs.existsSync(pkgPath)) continue;
+      const pkg = readPackageJson(pkgPath);
+      if (!pkg.name || !pkg.version) continue;
+      packages.push({
+        name: pkg.name,
+        version: pkg.version,
+        dir: path.join(wsPath, entry.name),
+        private: pkg.private === true,
+      });
+    }
+  }
+  return packages;
+}
+
+/** Result of one package publish attempt. */
+export interface PublishOutcome {
+  name: string;
+  version: string;
+  status: number;
+  stderr: string;
+}
+
+/** Injectable subprocess runner so the publish loop is testable. */
+export type CommandRunner = (args: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+}) => { status: number; stderr: string };
+
+const defaultRunner: CommandRunner = ({ command, args, cwd, env }) => {
+  const result = spawnSync(command, args, { cwd, env, encoding: "utf8" });
+  return {
+    status: result.status ?? 1,
+    stderr: `${result.stderr ?? ""}${result.error ? result.error.message : ""}`,
+  };
+};
+
+/**
+ * Publish every non-private discovered package to the local registry via
+ * `bun publish --registry <url>`. Returns one outcome per attempted
+ * package; the caller asserts each `status === 0`.
+ */
+export function publishWorkspacePackages({
+  packages,
+  registryUrl = DEFAULT_REGISTRY_URL,
+  npmrcPath,
+  run = defaultRunner,
+  env = process.env,
+}: {
+  packages: WorkspacePackage[];
+  registryUrl?: string;
+  npmrcPath: string;
+  run?: CommandRunner;
+  env?: NodeJS.ProcessEnv;
+}): PublishOutcome[] {
+  const publishArgs = buildBunPublishArgs({ registryUrl });
+  // Route bun/npm auth + registry through the throwaway .npmrc.
+  const childEnv: NodeJS.ProcessEnv = {
+    ...env,
+    NPM_CONFIG_USERCONFIG: npmrcPath,
+    BUN_CONFIG_REGISTRY: registryUrl,
+  };
+  const outcomes: PublishOutcome[] = [];
+  for (const pkg of packages) {
+    if (pkg.private) continue;
+    const { status, stderr } = run({
+      command: "bun",
+      args: publishArgs,
+      cwd: pkg.dir,
+      env: childEnv,
+    });
+    outcomes.push({ name: pkg.name, version: pkg.version, status, stderr });
+  }
+  return outcomes;
+}
+
+/** A live Verdaccio process handle plus its base URL. */
+export interface RegistryHandle {
+  url: string;
+  child: ChildProcess;
+  stop: () => Promise<void>;
+}
+
+/**
+ * Spawn Verdaccio via `npx verdaccio --config <file>` and wait until the
+ * registry answers HTTP. Used by the integration test only.
+ */
+export async function startVerdaccio({
+  configPath,
+  url = DEFAULT_REGISTRY_URL,
+  readyTimeoutMs = 60_000,
+}: {
+  configPath: string;
+  url?: string;
+  readyTimeoutMs?: number;
+}): Promise<RegistryHandle> {
+  const child = spawn("npx", ["--yes", "verdaccio", "--config", configPath], {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  const stop = async (): Promise<void> => {
+    if (child.exitCode === null && !child.killed) {
+      child.kill("SIGTERM");
+      await new Promise<void>((resolve) => {
+        const t = setTimeout(() => {
+          child.kill("SIGKILL");
+          resolve();
+        }, 3000);
+        child.on("exit", () => {
+          clearTimeout(t);
+          resolve();
+        });
+      });
+    }
+  };
+
+  const deadline = Date.now() + readyTimeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${url}/-/ping`);
+      if (res.ok || res.status === 404) {
+        // 404 still means the HTTP server is up and routing.
+        return { url, child, stop };
+      }
+    } catch {
+      // not up yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  await stop();
+  throw new Error(`Verdaccio did not become ready at ${url} in time`);
+}
+
+/**
+ * Locate the monorepo root by walking up from a starting dir until a
+ * `package.json` whose name is `checkstack-monorepo` (the root workspace)
+ * is found.
+ */
+export function findMonorepoRoot({ from }: { from: string }): string {
+  let dir = from;
+  for (let i = 0; i < 20; i++) {
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      const pkg = readPackageJson(pkgPath);
+      if (pkg.name === "checkstack-monorepo") return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`Could not find checkstack-monorepo root above ${from}`);
+}

package/src/npm-view-resolver.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "bun:test";
+import {
+  createNpmViewResolver,
+  buildNpmViewArgs,
+  type NpmViewRunner,
+} from "./npm-view-resolver";
+
+/** Records every package it was asked for and answers from a fixed table. */
+function fakeRunner(
+  versions: Record<string, string>,
+): { runner: NpmViewRunner; calls: string[] } {
+  const calls: string[] = [];
+  const runner: NpmViewRunner = ({ packageName }) => {
+    calls.push(packageName);
+    const v = versions[packageName];
+    return Promise.resolve(v ? { version: v } : { version: undefined });
+  };
+  return { runner, calls };
+}
+
+describe("buildNpmViewArgs", () => {
+  it("queries <pkg>@<tag> version with the default latest tag", () => {
+    expect(
+      buildNpmViewArgs({ packageName: "@checkstack/common" }),
+    ).toEqual(["view", "@checkstack/common@latest", "version"]);
+  });
+
+  it("threads a custom version tag", () => {
+    expect(
+      buildNpmViewArgs({ packageName: "@checkstack/common", versionTag: "next" }),
+    ).toEqual(["view", "@checkstack/common@next", "version"]);
+  });
+
+  it("threads a custom registry", () => {
+    expect(
+      buildNpmViewArgs({
+        packageName: "@checkstack/common",
+        registry: "http://localhost:4873",
+      }),
+    ).toEqual([
+      "view",
+      "@checkstack/common@latest",
+      "version",
+      "--registry",
+      "http://localhost:4873",
+    ]);
+  });
+});
+
+describe("createNpmViewResolver", () => {
+  it("resolves a published @checkstack/* dep to a caret on its latest version", async () => {
+    const { runner } = fakeRunner({ "@checkstack/common": "0.12.0" });
+    const resolve = createNpmViewResolver({ runNpmView: runner });
+
+    expect(
+      await resolve({
+        packageName: "@checkstack/common",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBe("^0.12.0");
+  });
+
+  it("resolves each @checkstack/* dep independently (not lockstepped)", async () => {
+    const { runner } = fakeRunner({
+      "@checkstack/common": "0.12.0",
+      "@checkstack/backend": "0.15.0",
+    });
+    const resolve = createNpmViewResolver({ runNpmView: runner });
+
+    expect(
+      await resolve({
+        packageName: "@checkstack/common",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBe("^0.12.0");
+    expect(
+      await resolve({
+        packageName: "@checkstack/backend",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBe("^0.15.0");
+  });
+
+  it("leaves local workspace siblings as workspace:* (not published)", async () => {
+    const { runner, calls } = fakeRunner({});
+    const resolve = createNpmViewResolver({
+      runNpmView: runner,
+      localSiblings: new Set(["widget-common", "widget-frontend"]),
+    });
+
+    expect(
+      await resolve({
+        packageName: "widget-common",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBe("workspace:*");
+    // The registry is never queried for a local sibling.
+    expect(calls).not.toContain("widget-common");
+  });
+
+  it("caches a resolution so the registry is queried once per package", async () => {
+    const { runner, calls } = fakeRunner({ "@checkstack/common": "0.12.0" });
+    const resolve = createNpmViewResolver({ runNpmView: runner });
+
+    await resolve({
+      packageName: "@checkstack/common",
+      workspaceRange: "workspace:*",
+    });
+    await resolve({
+      packageName: "@checkstack/common",
+      workspaceRange: "workspace:*",
+    });
+    expect(calls).toEqual(["@checkstack/common"]);
+  });
+
+  it("returns undefined for an unresolvable published dep so the engine can aggregate the failure", async () => {
+    const { runner } = fakeRunner({});
+    const resolve = createNpmViewResolver({ runNpmView: runner });
+
+    expect(
+      await resolve({
+        packageName: "@checkstack/common",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("propagates a subprocess failure (registry unreachable)", async () => {
+    const runner: NpmViewRunner = () =>
+      Promise.reject(new Error("npm view exited with status 1"));
+    const resolve = createNpmViewResolver({ runNpmView: runner });
+
+    await expect(
+      resolve({
+        packageName: "@checkstack/common",
+        workspaceRange: "workspace:*",
+      }),
+    ).rejects.toThrow(/npm view exited/);
+  });
+});

package/src/npm-view-resolver.ts

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import type { VersionResolver } from "@checkstack/scripts/scaffold";
+
+/**
+ * npm-view-backed {@link VersionResolver} for the standalone scaffolder.
+ *
+ * The scaffolding engine (in `@checkstack/scripts`) rewrites every
+ * `workspace:*` range in the rendered trio to a concrete version via an
+ * injected resolver. This is the production resolver: it queries the
+ * registry's `latest` dist-tag (or a `--version-tag`) per dependency via
+ * `npm view <pkg>@<tag> version` and pins a caret range (`^<version>`).
+ *
+ * Key behaviours:
+ *   - `@checkstack/*` versions are 0.x and NOT lockstepped, so each dep is
+ *     resolved independently (one `npm view` per package), with a single
+ *     in-process cache so repeated lookups hit the registry once.
+ *   - The three local trio siblings (`widget-common`, `widget-backend`,
+ *     `widget-frontend`) are NOT published; they install from the local
+ *     Bun workspace, so the resolver returns their `workspace:*` range
+ *     unchanged (and `plugin-pack --bundle` rewrites them at pack time).
+ *   - A registry miss returns `undefined` so the engine can aggregate and
+ *     fail loud with the full list of unresolved deps. A subprocess error
+ *     (registry unreachable) propagates as a thrown error.
+ */
+
+/** Result of querying the registry for one package's version. */
+export interface NpmViewResult {
+  /** The concrete version, or `undefined` if the package was not found. */
+  version: string | undefined;
+}
+
+/** Injectable subprocess seam: runs `npm view` for one package. */
+export type NpmViewRunner = (args: {
+  packageName: string;
+  registry?: string;
+  versionTag: string;
+}) => Promise<NpmViewResult>;
+
+/**
+ * Build the `npm view` argument vector for one package. Pure, so the exact
+ * registry/tag threading is unit-testable without spawning a process.
+ */
+export function buildNpmViewArgs({
+  packageName,
+  versionTag = "latest",
+  registry,
+}: {
+  packageName: string;
+  versionTag?: string;
+  registry?: string;
+}): string[] {
+  const args = ["view", `${packageName}@${versionTag}`, "version"];
+  if (registry) args.push("--registry", registry);
+  return args;
+}
+
+/**
+ * Default {@link NpmViewRunner}: spawns `npm view`, captures stdout, and
+ * parses the printed version. A non-zero exit (other than "package not
+ * found") rejects so the caller surfaces a clear network error.
+ */
+export const spawnNpmViewRunner: NpmViewRunner = ({
+  packageName,
+  registry,
+  versionTag,
+}) => {
+  const args = buildNpmViewArgs({ packageName, versionTag, registry });
+  return new Promise<NpmViewResult>((resolve, reject) => {
+    const child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const version = stdout.trim().replaceAll(/['"]/g, "") || undefined;
+      if (code === 0) {
+        resolve({ version });
+        return;
+      }
+      // `npm view` exits non-zero when the package is absent (E404). Treat
+      // that as "unresolved" (undefined) so the engine aggregates; any other
+      // failure (network, auth) is a hard error.
+      if (/E404|404 Not Found|is not in this registry/i.test(stderr)) {
+        resolve({ version: undefined });
+        return;
+      }
+      reject(
+        new Error(
+          `npm view ${packageName} exited with status ${code}: ${stderr.trim()}`,
+        ),
+      );
+    });
+  });
+};
+
+/**
+ * Create the npm-view-backed resolver.
+ *
+ * @param runNpmView injectable subprocess seam (defaults to a real
+ *   `npm view` spawn). Tests pass a fake.
+ * @param registry optional registry URL to thread into `npm view`.
+ * @param versionTag dist-tag to resolve (default `latest`).
+ * @param localSiblings the generated trio package names, left as
+ *   `workspace:*` because they resolve from the local workspace.
+ */
+export function createNpmViewResolver({
+  runNpmView = spawnNpmViewRunner,
+  registry,
+  versionTag = "latest",
+  localSiblings = new Set<string>(),
+}: {
+  runNpmView?: NpmViewRunner;
+  registry?: string;
+  versionTag?: string;
+  localSiblings?: Set<string>;
+} = {}): VersionResolver {
+  const cache = new Map<string, Promise<string | undefined>>();
+
+  return ({ packageName, workspaceRange }) => {
+    // Local trio siblings are not published: keep the workspace range so
+    // `bun install` resolves them from the local workspace.
+    if (localSiblings.has(packageName)) {
+      return Promise.resolve(workspaceRange);
+    }
+
+    const cached = cache.get(packageName);
+    if (cached) return cached;
+
+    const resolution = runNpmView({ packageName, registry, versionTag }).then(
+      ({ version }) => (version ? `^${version}` : undefined),
+    );
+    cache.set(packageName, resolution);
+    return resolution;
+  };
+}