@checkstack/scripts 0.3.3 → 0.4.0

package/src/scaffold/rewrite-workspace-versions.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared `workspace:*` -> concrete-version rewriting.
+ *
+ * Two consumers use this:
+ *   - `plugin-pack`, which rewrites a package's `workspace:*` deps to the
+ *     sibling's actual version before packing a tarball (so the published
+ *     artifact installs outside the monorepo).
+ *   - the scaffolding engine, which rewrites a freshly rendered template's
+ *     `workspace:*` deps to concrete published versions when generating a
+ *     standalone (non-monorepo) plugin repo.
+ *
+ * Both share the same range-detection shape (`startsWith("workspace:")`),
+ * so it lives here once. The *source* of the concrete version differs by
+ * caller, so it is injected via a {@link VersionResolver}.
+ */
+
+/** The dependency sections we rewrite, in a stable order. */
+export const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+] as const;
+
+export type DependencySection = (typeof DEPENDENCY_SECTIONS)[number];
+
+/**
+ * Resolves the concrete semver range to substitute for a `workspace:*`
+ * dependency. Implementations decide where the version comes from (a
+ * workspace sibling's `package.json`, an npm `latest` dist-tag, a test
+ * stub, ...). Returning `undefined` means "cannot resolve" and the caller
+ * decides whether that is fatal.
+ *
+ * The resolver is **async**: the standalone scaffolder's default resolver
+ * queries the registry (`npm view <pkg> version`) per dependency, and
+ * `@checkstack/*` versions are not lockstepped (0.x, resolved
+ * independently), so each lookup is its own network call that the engine
+ * fans out concurrently. The monorepo resolver is synchronous in spirit
+ * (it reads a sibling's `package.json` on disk) but returns a `Promise`
+ * to satisfy this single shared seam.
+ *
+ * @param packageName the dependency name, e.g. `@checkstack/common`.
+ * @param workspaceRange the original range, e.g. `workspace:*`.
+ */
+export type VersionResolver = (args: {
+  packageName: string;
+  workspaceRange: string;
+}) => Promise<string | undefined>;
+
+/** A `package.json` shape exposing the dependency sections we rewrite. */
+export type RewritablePackageJson = {
+  name?: string;
+} & Partial<Record<DependencySection, Record<string, string>>>;
+
+export interface RewriteResult {
+  /** Whether any range was changed. */
+  rewritten: boolean;
+  /** Dependency names whose range began with `workspace:` but resolved to nothing. */
+  unresolved: string[];
+}
+
+/**
+ * Rewrite every `workspace:`-prefixed range in the given package's
+ * dependency sections, mutating the package object in place.
+ *
+ * The resolver is invoked once per `workspace:` dep, and all invocations
+ * are fanned out concurrently (the standalone resolver hits the registry
+ * per package, so serializing them would be needlessly slow). When a
+ * resolver returns `undefined`, the range is left untouched and the name
+ * is recorded in {@link RewriteResult.unresolved} so the caller can fail
+ * loudly.
+ */
+export async function rewriteWorkspaceVersions({
+  pkg,
+  resolveVersion,
+}: {
+  pkg: RewritablePackageJson;
+  resolveVersion: VersionResolver;
+}): Promise<RewriteResult> {
+  const targets: { section: DependencySection; packageName: string }[] = [];
+  for (const section of DEPENDENCY_SECTIONS) {
+    const block = pkg[section];
+    if (!block) continue;
+    for (const [packageName, range] of Object.entries(block)) {
+      if (!range.startsWith("workspace:")) continue;
+      targets.push({ section, packageName });
+    }
+  }
+
+  const resolutions = await Promise.all(
+    targets.map(async ({ section, packageName }) => {
+      const workspaceRange = pkg[section]?.[packageName] ?? "";
+      const resolved = await resolveVersion({ packageName, workspaceRange });
+      return { section, packageName, resolved };
+    }),
+  );
+
+  let rewritten = false;
+  const unresolved: string[] = [];
+  for (const { section, packageName, resolved } of resolutions) {
+    if (resolved === undefined) {
+      unresolved.push(packageName);
+      continue;
+    }
+    const block = pkg[section];
+    if (!block) continue;
+    block[packageName] = resolved;
+    rewritten = true;
+  }
+
+  return { rewritten, unresolved };
+}

package/src/scaffold/scaffold-plugin.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  scaffoldPlugin,
+  refreshMonorepoReferences,
+  resolveTargetDir,
+  type ScaffoldIo,
+} from "./scaffold-plugin";
+import type { VersionResolver } from "./rewrite-workspace-versions";
+import type { copyTemplate } from "../utils/template";
+
+const tmpDirs: string[] = [];
+
+function makeTmpDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "scaffold-engine-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const constantResolver =
+  (version: string): VersionResolver =>
+  () =>
+    Promise.resolve(version);
+
+/** Records the copyTemplate args and writes nothing real. */
+function recordingCopyTemplate(): {
+  spy: typeof copyTemplate;
+  calls: { templateDir: string; targetDir: string }[];
+} {
+  const calls: { templateDir: string; targetDir: string }[] = [];
+  const spy: typeof copyTemplate = ({ templateDir, targetDir }) => {
+    calls.push({ templateDir, targetDir });
+    return [];
+  };
+  return { spy, calls };
+}
+
+describe("resolveTargetDir", () => {
+  it("uses <rootDir>/<location>/<name> in monorepo mode", () => {
+    expect(
+      resolveTargetDir({
+        mode: { kind: "monorepo", rootDir: "/repo", location: "plugins" },
+        pluginName: "widget-backend",
+      }),
+    ).toBe(path.join("/repo", "plugins", "widget-backend"));
+  });
+
+  it("uses <targetDir>/<name> in standalone mode", () => {
+    expect(
+      resolveTargetDir({
+        mode: { kind: "standalone", targetDir: "/out" },
+        pluginName: "widget-backend",
+      }),
+    ).toBe(path.join("/out", "widget-backend"));
+  });
+});
+
+describe("scaffoldPlugin — mode parameterization", () => {
+  it("renders the matching template dir into the monorepo target", async () => {
+    const { spy, calls } = recordingCopyTemplate();
+    const io: Partial<ScaffoldIo> = { copyTemplate: spy };
+
+    const result = await scaffoldPlugin({
+      mode: { kind: "monorepo", rootDir: "/repo", location: "core" },
+      baseName: "widget",
+      description: "Widget plugin",
+      pluginType: "backend",
+      io,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].templateDir).toEndWith(path.join("templates", "backend"));
+    expect(calls[0].targetDir).toBe(
+      path.join("/repo", "core", "widget-backend"),
+    );
+    expect(result.templateData.pluginName).toBe("widget-backend");
+    expect(result.templateData.pluginId).toBe("widget-backend");
+  });
+
+  it("does not rewrite versions in monorepo mode", async () => {
+    const targetRoot = makeTmpDir();
+    // Real render so a package.json with workspace:* lands on disk.
+    await scaffoldPlugin({
+      mode: { kind: "monorepo", rootDir: targetRoot, location: "core" },
+      baseName: "widget",
+      description: "Widget plugin",
+      pluginType: "common",
+    });
+    const pkg = JSON.parse(
+      fs.readFileSync(
+        path.join(targetRoot, "core", "widget-common", "package.json"),
+        "utf8",
+      ),
+    ) as { dependencies?: Record<string, string> };
+    const ranges = Object.values(pkg.dependencies ?? {});
+    expect(ranges.some((r) => r.startsWith("workspace:"))).toBe(true);
+  });
+
+  it("throws in standalone mode when no resolveVersion is supplied", async () => {
+    const { spy } = recordingCopyTemplate();
+    await expect(
+      scaffoldPlugin({
+        mode: { kind: "standalone", targetDir: makeTmpDir() },
+        baseName: "widget",
+        description: "Widget plugin",
+        pluginType: "backend",
+        io: { copyTemplate: spy },
+      }),
+    ).rejects.toThrow(/standalone mode requires a `resolveVersion`/);
+  });
+
+  it("rewrites every workspace range to a concrete version in standalone mode", async () => {
+    const out = makeTmpDir();
+    await scaffoldPlugin({
+      mode: { kind: "standalone", targetDir: out },
+      baseName: "widget",
+      description: "Widget plugin",
+      pluginType: "backend",
+      resolveVersion: constantResolver("^1.2.3"),
+    });
+
+    const pkg = JSON.parse(
+      fs.readFileSync(
+        path.join(out, "widget-backend", "package.json"),
+        "utf8",
+      ),
+    ) as Record<string, Record<string, string> | undefined>;
+
+    const allRanges = [
+      ...Object.values(pkg.dependencies ?? {}),
+      ...Object.values(pkg.devDependencies ?? {}),
+      ...Object.values(pkg.peerDependencies ?? {}),
+    ];
+    expect(allRanges.some((r) => r.startsWith("workspace:"))).toBe(false);
+    // Every @checkstack/* dep is now the concrete resolved version.
+    expect(pkg.dependencies?.["@checkstack/common"]).toBe("^1.2.3");
+    expect(pkg.devDependencies?.["@checkstack/scripts"]).toBe("^1.2.3");
+  });
+
+  it("reports the rewrite through the io.log seam in standalone mode", async () => {
+    const out = makeTmpDir();
+    const logs: string[] = [];
+    await scaffoldPlugin({
+      mode: { kind: "standalone", targetDir: out },
+      baseName: "widget",
+      description: "Widget plugin",
+      pluginType: "backend",
+      resolveVersion: constantResolver("^1.2.3"),
+      io: { log: (m) => logs.push(m) },
+    });
+    expect(logs.some((m) => m.includes("Resolved workspace versions"))).toBe(
+      true,
+    );
+  });
+
+  it("fails loudly if a workspace dep cannot be resolved in standalone mode", async () => {
+    const out = makeTmpDir();
+    const failing: VersionResolver = () => Promise.resolve(undefined);
+    await expect(
+      scaffoldPlugin({
+        mode: { kind: "standalone", targetDir: out },
+        baseName: "widget",
+        description: "Widget plugin",
+        pluginType: "backend",
+        resolveVersion: failing,
+      }),
+    ).rejects.toThrow(/must not emit 'workspace:\*'/);
+  });
+});
+
+describe("refreshMonorepoReferences — gated by mode", () => {
+  it("invokes the refresh in monorepo mode", () => {
+    let called = 0;
+    const status = refreshMonorepoReferences({
+      mode: { kind: "monorepo", rootDir: "/repo", location: "core" },
+      io: {
+        refreshReferences: () => {
+          called += 1;
+          return 0;
+        },
+      },
+    });
+    expect(called).toBe(1);
+    expect(status).toBe(0);
+  });
+
+  it("is a no-op in standalone mode", () => {
+    let called = 0;
+    const status = refreshMonorepoReferences({
+      mode: { kind: "standalone", targetDir: "/out" },
+      io: {
+        refreshReferences: () => {
+          called += 1;
+          return 0;
+        },
+      },
+    });
+    expect(called).toBe(0);
+    expect(status).toBe(0);
+  });
+});

package/src/scaffold/scaffold-plugin.ts

@@ -0,0 +1,309 @@
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  copyTemplate,
+  prepareTemplateData,
+  registerHelpers,
+  type TemplateData,
+} from "../utils/template";
+import {
+  rewriteWorkspaceVersions,
+  type VersionResolver,
+} from "./rewrite-workspace-versions";
+
+/**
+ * Monorepo-decoupled scaffolding engine.
+ *
+ * The engine takes a {@link ScaffoldMode} plus a base name / description /
+ * package type and renders the matching `templates/<type>` directory into a
+ * target directory. It performs **no** `process.cwd()` reads of its own —
+ * the caller supplies `rootDir` (monorepo) or `targetDir` (standalone), so
+ * the same code runs both in-monorepo (`create`) and from a standalone
+ * bootstrapper (`create-checkstack-plugin`, Phase 2).
+ *
+ * Mode-specific behaviour:
+ *   - `monorepo`: writes into `<rootDir>/<location>/<name>`, keeps the
+ *     template's `workspace:*` ranges verbatim, and refreshes the root
+ *     TypeScript project references afterwards.
+ *   - `standalone`: writes into `<targetDir>/<name>` (or a caller-chosen
+ *     layout) and rewrites every `workspace:*` range to a concrete version
+ *     via the injected {@link VersionResolver}. No references refresh —
+ *     standalone repos don't use the root references graph.
+ */
+
+const SCAFFOLD_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/** Directory holding the per-type template trees. */
+export const TEMPLATES_DIR = path.resolve(SCAFFOLD_DIR, "..", "templates");
+
+export type ScaffoldMode =
+  | { kind: "monorepo"; rootDir: string; location: "core" | "plugins" }
+  | { kind: "standalone"; targetDir: string };
+
+/** IO seam so tests can inject fakes for fs/spawn/logging. */
+export interface ScaffoldIo {
+  /**
+   * Render a template directory into a target directory. Defaults to the
+   * real Handlebars-backed {@link copyTemplate}.
+   */
+  copyTemplate: typeof copyTemplate;
+  /**
+   * Refresh the monorepo's TypeScript project references. Only invoked in
+   * `monorepo` mode. Returns the exit status (0 = success).
+   */
+  refreshReferences: () => number;
+  log: (message: string) => void;
+  warn: (message: string) => void;
+}
+
+export interface ScaffoldPluginOptions {
+  mode: ScaffoldMode;
+  /** e.g. "widget" — combined with the type to form "widget-backend". */
+  baseName: string;
+  description: string;
+  pluginType: string;
+  /**
+   * npm scope (without `@`) for the generated package. Defaults to
+   * `checkstack` (the monorepo scope, so the in-monorepo `create` path is
+   * unchanged); pass `""` for an unscoped standalone package.
+   */
+  packageScope?: string;
+  /**
+   * Resolve a concrete version for an `@checkstack/*` `workspace:*` dep.
+   * Required in `standalone` mode; ignored in `monorepo` mode (templates
+   * keep their `workspace:*` ranges so the workspace resolves them).
+   */
+  resolveVersion?: VersionResolver;
+  /** Override the IO seam (tests). Defaults to the real filesystem. */
+  io?: Partial<ScaffoldIo>;
+}
+
+export interface ScaffoldPluginResult {
+  /** The directory the package was written into. */
+  targetDir: string;
+  /** Absolute paths of every file written. */
+  createdFiles: string[];
+  templateData: TemplateData;
+}
+
+/** Default IO seam: real filesystem + a root references refresh via bun. */
+function defaultIo(): ScaffoldIo {
+  return {
+    copyTemplate,
+    refreshReferences: () => {
+      const result = spawnSync(
+        "bun",
+        ["run", "typecheck:references:generate"],
+        { stdio: "inherit" },
+      );
+      return result.status ?? 0;
+    },
+    log: (message) => {
+      console.log(message);
+    },
+    warn: (message) => {
+      console.warn(message);
+    },
+  };
+}
+
+/**
+ * Resolve the on-disk target directory for a given mode + plugin name.
+ *
+ * `monorepo` mirrors the historical `create` layout
+ * (`<rootDir>/<location>/<name>`); `standalone` writes `<targetDir>/<name>`.
+ */
+export function resolveTargetDir({
+  mode,
+  pluginName,
+}: {
+  mode: ScaffoldMode;
+  pluginName: string;
+}): string {
+  return mode.kind === "monorepo"
+    ? path.join(mode.rootDir, mode.location, pluginName)
+    : path.join(mode.targetDir, pluginName);
+}
+
+/**
+ * Read, rewrite, and write back the `workspace:*` ranges in a rendered
+ * `package.json`. Throws (listing the offending names) if any
+ * `workspace:` range cannot be resolved — never silently emits
+ * `workspace:*`, which the runtime install-time validator rejects.
+ */
+async function rewriteRenderedPackageJson({
+  targetDir,
+  resolveVersion,
+  io,
+}: {
+  targetDir: string;
+  resolveVersion: VersionResolver;
+  io: ScaffoldIo;
+}): Promise<void> {
+  const pkgJsonPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) {
+    io.warn(
+      `No package.json found in ${targetDir}; skipped version rewriting.`,
+    );
+    return;
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const { rewritten, unresolved } = await rewriteWorkspaceVersions({
+    pkg,
+    resolveVersion,
+  });
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Could not resolve concrete versions for ${unresolved.length} ` +
+        `workspace dependenc${unresolved.length === 1 ? "y" : "ies"}: ` +
+        `${unresolved.join(", ")}. ` +
+        `A standalone scaffold must not emit 'workspace:*' ranges.`,
+    );
+  }
+  if (rewritten) {
+    fs.writeFileSync(pkgJsonPath, `${JSON.stringify(pkg, undefined, 2)}\n`);
+    io.log(`Resolved workspace versions in ${path.basename(targetDir)}.`);
+  }
+}
+
+/**
+ * Render one plugin package type into the mode-appropriate target dir.
+ *
+ * Behaviour-preserving for the in-monorepo `create` command: same target
+ * layout, same `copyTemplate`, same references refresh. Standalone mode
+ * additionally rewrites `workspace:*` ranges to concrete versions.
+ */
+export async function scaffoldPlugin({
+  mode,
+  baseName,
+  description,
+  pluginType,
+  packageScope = "checkstack",
+  resolveVersion,
+  io,
+}: ScaffoldPluginOptions): Promise<ScaffoldPluginResult> {
+  registerHelpers();
+
+  const resolvedIo: ScaffoldIo = { ...defaultIo(), ...io };
+
+  const templateData = prepareTemplateData({
+    baseName,
+    pluginType,
+    description,
+    packageScope,
+  });
+
+  const templateDir = path.join(TEMPLATES_DIR, pluginType);
+  const targetDir = resolveTargetDir({
+    mode,
+    pluginName: templateData.pluginName,
+  });
+
+  const createdFiles = resolvedIo.copyTemplate({
+    templateDir,
+    targetDir,
+    data: templateData,
+  });
+
+  if (mode.kind === "standalone") {
+    if (!resolveVersion) {
+      throw new Error(
+        "scaffoldPlugin in standalone mode requires a `resolveVersion` " +
+          "resolver to rewrite workspace ranges to concrete versions.",
+      );
+    }
+    await rewriteRenderedPackageJson({
+      targetDir,
+      resolveVersion,
+      io: resolvedIo,
+    });
+  }
+
+  return { targetDir, createdFiles, templateData };
+}
+
+/**
+ * Directory holding the standalone-only root workspace templates (root
+ * `package.json`, tsconfig, eslint, README, `.gitignore`, changeset
+ * config). Rendered only by {@link scaffoldStandaloneRoot}.
+ */
+export const STANDALONE_ROOT_TEMPLATE_DIR = path.join(
+  TEMPLATES_DIR,
+  "standalone-root",
+);
+
+export interface ScaffoldStandaloneRootResult {
+  /** The repo root directory the workspace files were written into. */
+  rootDir: string;
+  createdFiles: string[];
+  templateData: TemplateData;
+}
+
+/**
+ * Render the standalone repo's root workspace files into `rootDir`.
+ *
+ * This is the wrapper around the per-type trio that turns three loose
+ * packages into an installable local Bun workspace: a private root
+ * `package.json` with `workspaces: ["packages/*"]` and forwarding scripts
+ * (`dev`/`pack`/`typecheck`/`lint`/`test`), a root tsconfig, a
+ * self-contained eslint config, a `.gitignore`, a quickstart README, and a
+ * changeset config + initial changeset. Standalone-only: the in-monorepo
+ * `create` command never calls this.
+ */
+export function scaffoldStandaloneRoot({
+  rootDir,
+  baseName,
+  description,
+  packageScope = "checkstack",
+  io,
+}: {
+  rootDir: string;
+  baseName: string;
+  description: string;
+  packageScope?: string;
+  io?: Partial<ScaffoldIo>;
+}): ScaffoldStandaloneRootResult {
+  registerHelpers();
+  const resolvedIo: ScaffoldIo = { ...defaultIo(), ...io };
+
+  // The root files describe the workspace as a whole, not one plugin type;
+  // we reuse prepareTemplateData with a sentinel "plugin" type so the
+  // pascal/camel/id derivations are available to the root templates.
+  const templateData = prepareTemplateData({
+    baseName,
+    pluginType: "plugin",
+    description,
+    packageScope,
+  });
+
+  const createdFiles = resolvedIo.copyTemplate({
+    templateDir: STANDALONE_ROOT_TEMPLATE_DIR,
+    targetDir: rootDir,
+    data: templateData,
+  });
+
+  return { rootDir, createdFiles, templateData };
+}
+
+/**
+ * Refresh the monorepo's TypeScript project references. No-op outside
+ * `monorepo` mode (standalone repos do not use the root references graph).
+ * Returns the exit status; non-zero means the refresh failed and the
+ * caller should warn the user to run it manually.
+ */
+export function refreshMonorepoReferences({
+  mode,
+  io,
+}: {
+  mode: ScaffoldMode;
+  io?: Partial<ScaffoldIo>;
+}): number {
+  if (mode.kind !== "monorepo") return 0;
+  const resolvedIo: ScaffoldIo = { ...defaultIo(), ...io };
+  return resolvedIo.refreshReferences();
+}

package/src/templates/backend/.changeset/initial.md.hbs

@@ -1,4 +1,4 @@
---- "@checkstack/{{pluginName}}": patch --- Initial release of
+--- "{{scoped pluginName}}": patch --- Initial release of
 {{pluginNamePascal}}
 backend plugin
 

package/src/templates/backend/drizzle/0000_init.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "items" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);