@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/vite-plugin/tests/support.ts

@@ -0,0 +1,339 @@
+/**
+ * Helpers for the plugin tests that run a real Vite server or build against a
+ * temporary app.
+ */
+import type { ChildProcess } from "node:child_process"
+import { EventEmitter } from "node:events"
+import fs from "node:fs"
+import http from "node:http"
+import Module, { createRequire } from "node:module"
+import type { AddressInfo } from "node:net"
+import os from "node:os"
+import path from "node:path"
+import { PassThrough } from "node:stream"
+import { fileURLToPath } from "node:url"
+import {
+  build,
+  createLogger,
+  createServer,
+  version as viteVersion,
+  type Logger,
+  type Plugin,
+  type ServerOptions,
+  type ViteDevServer,
+} from "vite"
+import { icReactor, type IcReactorPluginOptions } from "../src/index.js"
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+/** The ICRC-1 ledger interface, the module every example generates. */
+export const LEDGER_DID = path.join(HERE, "fixtures", "icrc1.did")
+
+/** A `.did` the real generator cannot parse. */
+export const BROKEN_DID = "service : { greet : (text) -> (text query\n"
+
+/** A `.did` the generator accepts, for a canister that is not the point of a test. */
+export const PING_DID = "service : { ping : () -> () };\n"
+
+const FAKE_CLI = path.join(HERE, "fixtures", "fake-cli")
+
+/**
+ * The `server.watch` that starts no file watcher. Vite 5 and later take
+ * `null`. Vite 4, the oldest major the peer range accepts and which
+ * `verify:peer-floors` runs these tests on, has no such value and reads
+ * `null` as the default watcher, whose events would double the ones the tests
+ * emit: there the watcher ignores every path instead.
+ */
+const NO_WATCHER = (
+  Number(viteVersion.split(".")[0]) < 5 ? { ignored: ["**"] } : null
+) as ServerOptions["watch"]
+
+/**
+ * Remove a test's temporary directory. On Windows a file in it can still be
+ * open for a moment after the process or watcher that held it ended, and the
+ * removal fails with EBUSY or EPERM, which Node tries again on (#905).
+ */
+export function removeDirectory(directory: string): void {
+  fs.rmSync(directory, {
+    recursive: true,
+    force: true,
+    maxRetries: 10,
+    retryDelay: 100,
+  })
+}
+
+/**
+ * Every process that `spawn`, a `vi.fn` over the real one, started has
+ * exited. A server's close kills the generator it is running, but on Windows
+ * the killed process holds the app directory, its working directory, until
+ * it is gone. Removing the app before then fails with EBUSY on the directory
+ * itself, which `fs.rmSync` does not try again (#905).
+ */
+export async function spawnedExited(spawn: {
+  mock: { results: Array<{ type: string; value: unknown }> }
+}): Promise<void> {
+  await Promise.all(
+    spawn.mock.results
+      .flatMap(({ type, value }) =>
+        type === "return" ? [value as ChildProcess] : []
+      )
+      .filter((child) => child.exitCode === null && child.signalCode === null)
+      .map((child) => new Promise((resolve) => child.once("exit", resolve)))
+  )
+}
+
+/**
+ * The server options of a middleware-mode server without a WebSocket, which
+ * binds no port. `hmr: false` alone is not that: Vite still opens a WebSocket
+ * server then, on the fixed port 24678, so two servers at once (two test
+ * files, or any other middleware-mode Vite on the machine) collide. Vite 4
+ * fails with EADDRINUSE, and from Vite 5 on the server logs an error, which
+ * the tests that count logged errors see. Vite 6 and later take `ws: false`
+ * (not in Vite 4's types, hence the cast). Vite 4 and 5, which
+ * `verify:peer-floors` runs these tests on, do not: there the WebSocket is
+ * attached to an HTTP server that never listens.
+ */
+export function noWebSocket(): Pick<ServerOptions, "hmr"> {
+  return Number(viteVersion.split(".")[0]) >= 6
+    ? ({ hmr: false, ws: false } as Pick<ServerOptions, "hmr">)
+    : { hmr: { server: http.createServer() } }
+}
+
+export interface App {
+  /** The app's root: a real path, since Vite compares real paths. */
+  root: string
+  /** What the stand-in CLI recorded: one entry per process it ran. */
+  runs: () => string[][]
+  cleanup: () => void
+}
+
+/**
+ * A temporary app with `files` (relative path to text) and a CLI installed in
+ * its `node_modules` the way an app installs it: the real `@meantjs/cli`
+ * this package depends on (`"real"`), or a stand-in that crashes or hangs on a
+ * `.did` that says TRAP or HANG (`"fake"`), or none (`"none"`).
+ */
+export function createApp(
+  files: Record<string, string>,
+  cli: "real" | "fake" | "none"
+): App {
+  // The native realpath, as the plugin's: on Windows the temporary directory
+  // can be spelled with 8.3 short names (C:\Users\RUNNER~1), which only it
+  // expands, and the paths the tests expect must be the ones the plugin gives
+  // the generator (#905).
+  const root = fs.realpathSync.native(
+    fs.mkdtempSync(path.join(os.tmpdir(), "ic-reactor-vite-"))
+  )
+  const all: Record<string, string> = {
+    "index.html":
+      '<!doctype html><html><body><script type="module" src="/main.js"></script></body></html>\n',
+    "main.js": 'console.log("app")\n',
+    ...files,
+  }
+  for (const [file, text] of Object.entries(all)) {
+    fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true })
+    fs.writeFileSync(path.join(root, file), text)
+  }
+
+  const installed = path.join(root, "node_modules", "@meantjs", "cli")
+  if (cli === "real") {
+    const manifest = createRequire(import.meta.url).resolve(
+      "@meantjs/cli/package.json"
+    )
+    fs.mkdirSync(path.dirname(installed), { recursive: true })
+    fs.symlinkSync(path.dirname(manifest), installed, "junction")
+  } else if (cli === "fake") {
+    fs.mkdirSync(installed, { recursive: true })
+    for (const file of ["package.json", "bin.js"]) {
+      fs.copyFileSync(path.join(FAKE_CLI, file), path.join(installed, file))
+    }
+  }
+
+  return {
+    root,
+    runs: () => {
+      try {
+        return fs
+          .readFileSync(path.join(installed, "runs.log"), "utf-8")
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line) as string[])
+      } catch {
+        return []
+      }
+    },
+    cleanup: () => removeDirectory(root),
+  }
+}
+
+export interface RecordingLogger {
+  logger: Logger
+  /** Every line logged, as `"<level>: <message>"`, in order. */
+  lines: string[]
+}
+
+/** A Vite logger that records what it is asked to log instead of printing it. */
+export function recordingLogger(): RecordingLogger {
+  const lines: string[] = []
+  const logger = createLogger("info")
+  const record = (level: string) => (message: string) => {
+    lines.push(`${level}: ${message}`)
+  }
+  return {
+    lines,
+    logger: {
+      ...logger,
+      info: record("info"),
+      warn: record("warn"),
+      warnOnce: record("warn"),
+      error: record("error"),
+    },
+  }
+}
+
+/**
+ * Run `run` with `NODE_PATH` unset. Under `pnpm test`, pnpm sets it to its own
+ * `node_modules`, where the real `@meantjs/cli` is installed, so an app
+ * with no CLI of its own would find one all the same. Node reads `NODE_PATH`
+ * once at startup, so it has to be read again after the change.
+ */
+export async function withoutNodePath<T>(run: () => Promise<T>): Promise<T> {
+  const saved = process.env.NODE_PATH
+  const initPaths = () =>
+    (Module as unknown as { _initPaths(): void })._initPaths()
+  delete process.env.NODE_PATH
+  initPaths()
+  try {
+    return await run()
+  } finally {
+    if (saved !== undefined) process.env.NODE_PATH = saved
+    initPaths()
+  }
+}
+
+export interface Running {
+  server: ViteDevServer
+  port: number
+  /** What the server's logger was asked to log. */
+  lines: string[]
+  close: () => Promise<void>
+}
+
+/**
+ * `vite dev` over `root`, as its middlewares, on a free port.
+ *
+ * Its file watcher is off by default and the tests deliver the events they
+ * mean to by emitting them: a real watcher on a directory created a moment
+ * ago sometimes reports the files in it, which starts a run nobody asked for.
+ * `realWatcher` keeps it. `hmr: false` is the server without a WebSocket
+ * (`noWebSocket`). `mode: "test"` is the server Vitest starts. The
+ * environment half of the plugin is off, so no test runs `icp`.
+ */
+export async function startDev(
+  root: string,
+  options: IcReactorPluginOptions,
+  {
+    before = [] as Plugin[],
+    realWatcher = false,
+    hmr = true,
+    mode = undefined as string | undefined,
+  } = {}
+): Promise<Running> {
+  const { logger, lines } = recordingLogger()
+  const httpServer = http.createServer()
+  const server = await createServer({
+    root,
+    configFile: false,
+    mode,
+    customLogger: logger,
+    server: {
+      middlewareMode: true,
+      ...(hmr ? { hmr: { server: httpServer } } : noWebSocket()),
+      watch: realWatcher ? undefined : NO_WATCHER,
+    },
+    plugins: [...before, icReactor({ injectEnvironment: false, ...options })],
+  })
+  httpServer.on("request", server.middlewares)
+  await new Promise<void>((resolve) =>
+    httpServer.listen(0, "127.0.0.1", () => resolve())
+  )
+  return {
+    server,
+    port: (httpServer.address() as AddressInfo).port,
+    lines,
+    close: async () => {
+      await server.close()
+      await new Promise((resolve) => httpServer.close(resolve))
+    },
+  }
+}
+
+/** `vite build` over `root`, writing nothing, and the lines it logged. */
+export function runBuild(root: string, options: IcReactorPluginOptions) {
+  const { logger, lines } = recordingLogger()
+  const result = build({
+    root,
+    configFile: false,
+    customLogger: logger,
+    build: { write: false },
+    plugins: [icReactor(options)],
+  })
+  return { result, lines }
+}
+
+/** A page request, as a browser makes it. */
+export function get(port: number, pathname: string) {
+  return new Promise<{ status: number; body: string }>((resolve, reject) => {
+    http
+      .get(
+        {
+          host: "127.0.0.1",
+          port,
+          path: pathname,
+          headers: { accept: "text/html" },
+        },
+        (res) => {
+          let body = ""
+          res.setEncoding("utf-8")
+          res.on("data", (chunk: string) => (body += chunk))
+          res.on("end", () => resolve({ status: res.statusCode ?? 0, body }))
+        }
+      )
+      .on("error", reject)
+  })
+}
+
+/**
+ * What a mocked `spawn` hands back for an `icp` command: a process that
+ * writes `result` to stdout and exits 0, or for an Error, writes its `stderr`
+ * (its message when it has none, as a real `icp` writes its error) and exits
+ * 1. An Error whose `code` is `ENOENT` is a command that never started. It
+ * settles later, as a real process does.
+ */
+export function icpProcess(result: string | Error) {
+  const child = Object.assign(new EventEmitter(), {
+    stdout: new PassThrough(),
+    stderr: new PassThrough(),
+    stdin: new PassThrough(),
+    pid: undefined,
+    kill: () => true,
+  })
+  setImmediate(() => {
+    if (
+      result instanceof Error &&
+      (result as { code?: unknown }).code === "ENOENT"
+    ) {
+      child.emit("error", result)
+      child.emit("close", -2, null)
+      return
+    }
+    const failed = result instanceof Error
+    child.stdout.end(failed ? "" : result)
+    child.stderr.end(
+      failed ? ((result as { stderr?: string }).stderr ?? result.message) : ""
+    )
+    // After the streams have ended, as a real process closes.
+    setImmediate(() => child.emit("close", failed ? 1 : 0, null))
+  })
+  return child
+}

package/packages/vite-plugin/tests/timeout.test.ts

@@ -0,0 +1,107 @@
+/**
+ * A generator that never exits is killed at the timeout, and costs the
+ * canister it hung on and the dev server nothing but the wait.
+ *
+ * The timeout is 60 s. These tests shorten it by replacing the constant the
+ * plugin reads from its generator module, which is not an option of the
+ * plugin.
+ */
+import fs from "node:fs"
+import path from "node:path"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { createApp, get, runBuild, startDev, type App } from "./support.js"
+
+vi.mock("../src/generate.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../src/generate.js")>()),
+  GENERATE_TIMEOUT_MS: 1000,
+}))
+
+const closers: Array<() => Promise<unknown>> = []
+let app: App | undefined
+
+afterEach(async () => {
+  for (const close of closers.splice(0).reverse()) await close()
+  app?.cleanup()
+  app = undefined
+})
+
+/** Whether any process that the stand-in CLI hung in is still running. */
+function hungProcessIsAlive(root: string): boolean {
+  const pids = fs
+    .readFileSync(
+      path.join(root, "node_modules/@meantjs/cli/hang.pids"),
+      "utf-8"
+    )
+    .trim()
+    .split("\n")
+    .map(Number)
+  expect(pids.length).toBeGreaterThan(0)
+  return pids.some((pid) => {
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  })
+}
+
+describe("a generator that never exits", () => {
+  it("is killed at the timeout, and the build fails with that", async () => {
+    app = createApp({ "did/hang.did": "HANG\n" }, "fake")
+    const { result } = runBuild(app.root, {
+      canisters: { hang: { didFile: "did/hang.did" } },
+    })
+
+    await expect(result).rejects.toThrow(
+      /hang \(did\/hang\.did\): `meant` did not finish within 1s and was killed/
+    )
+    expect(hungProcessIsAlive(app.root)).toBe(false)
+  })
+
+  // The hang is one .did's, and the canisters that were generated with it are
+  // not its victims: each is run alone once the group has been killed.
+  it("costs only the canister that hung, and the build fails with that one", async () => {
+    app = createApp({ "did/hang.did": "HANG\n", "did/ok.did": "ok\n" }, "fake")
+    const { result, lines } = runBuild(app.root, {
+      canisters: {
+        hang: { didFile: "did/hang.did" },
+        ok: { didFile: "did/ok.did" },
+      },
+    })
+
+    await expect(result).rejects.toThrow(
+      /could not generate 1 of 2 canisters:\n {2}- hang \(did\/hang\.did\): `meant` did not finish within 1s and was killed/
+    )
+    expect(lines).toContain(
+      "info: ic-reactor: generated ok into src/canisters/ok.ts"
+    )
+    expect(hungProcessIsAlive(app.root)).toBe(false)
+  })
+
+  it("is killed at the timeout, and the dev server serves the canister that did not hang", async () => {
+    app = createApp({ "did/hang.did": "HANG\n", "did/ok.did": "ok\n" }, "fake")
+    const running = await startDev(app.root, {
+      canisters: {
+        hang: { didFile: "did/hang.did" },
+        ok: { didFile: "did/ok.did" },
+      },
+    })
+    closers.push(running.close)
+
+    expect(hungProcessIsAlive(app.root)).toBe(false)
+    expect((await get(running.port, "/")).status).toBe(200)
+    const errors = running.lines.filter((line) => line.startsWith("error:"))
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain("could not generate 1 of 2 canisters")
+    expect(errors[0]).toContain("hang (did/hang.did)")
+    expect(errors[0]).toContain("did not finish within 1s and was killed")
+    expect(errors[0]).not.toContain("ok (")
+    expect(running.lines).toContain(
+      "info: ic-reactor: generated ok into src/canisters/ok.ts"
+    )
+    // The group, then each of its two canisters alone. The one that hung is
+    // not tried a third time.
+    expect(app.runs().map((args) => args.length)).toEqual([6, 5, 5])
+  })
+})

package/packages/vite-plugin/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "ignoreDeprecations": "6.0",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/vite-plugin/tsconfig.typecheck.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "incremental": false,
+    "types": ["node"],
+    "rootDir": ".",
+    "noUnusedLocals": false
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/vite-plugin/vitest.config.ts

@@ -0,0 +1,9 @@
+/// <reference types="vitest" />
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: true,
+  },
+})

package/pnpm-workspace.yaml

@@ -0,0 +1,23 @@
+nodeVersion: "22.22.2"
+# Link local packages/* into workspace examples when their semver range matches
+# (e.g. "@ic-reactor/react": "^3.6.0" resolves to packages/react). Without this,
+# pnpm v10 defaults to false and tries to fetch the (possibly unpublished)
+# packages from the npm registry. StackBlitz/CodeSandbox run a plain install
+# outside this workspace, so they still use the pinned npm versions.
+linkWorkspacePackages: true
+# Astro renders Markdown with satteri, whose prerender bundle loads the native
+# binding `@bruits/satteri-<platform>` by bare name. pnpm links that optional
+# package only in the hidden hoist under node_modules/.pnpm, and an in-place
+# install across an Astro bump can drop that one link while the package stays
+# on disk. `pnpm docs:build` then fails with "Cannot find native binding" and a
+# plain `pnpm install` does not relink it (issue #408). Public hoisting puts the
+# binding in the root node_modules, where the bundle resolves it either way.
+publicHoistPattern:
+  - "@bruits/*"
+packages:
+  - "packages/*"
+  - "e2e"
+  - "scripts/size-app"
+  - "docs"
+  - "examples/*"
+  - "examples/*/*"

package/scripts/ai-context-files.js

@@ -0,0 +1,72 @@
+import { existsSync, readdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/**
+ * The single list of files whose version references must stay current.
+ *
+ * `check-ai-context.js` validates these and `release.js` rewrites them, so the
+ * two cannot disagree about which files a release has to update.
+ *
+ * On the v4 line the list is short on purpose: the one consumer guide,
+ * `packages/core/llms.txt` (shipped in core's tarball), the two contributor
+ * files, and what the DX3 slice adds when it lands: a pointer `llms.txt` in
+ * `packages/react` and the one consumer skill,
+ * `skill-packages/ic-reactor/SKILL.md` with its `references/`. Those are listed
+ * when they exist, so the check covers them from the commit that adds them,
+ * with no second edit here to forget. The three files below are required: a
+ * rename or a deletion fails `check-ai-context.js` with "Missing AI-context
+ * file".
+ */
+const REQUIRED = ["packages/core/llms.txt", "AGENTS.md", "CLAUDE.md"]
+
+/** Listed when present. */
+const OPTIONAL = [
+  "packages/react/llms.txt",
+  "skill-packages/ic-reactor/SKILL.md",
+]
+
+/** The consumer skill's folder: its references are AI context too. */
+const SKILL_REFERENCES = "skill-packages/ic-reactor/references"
+
+/**
+ * The AI-context files of the tree at `rootDir`.
+ *
+ * @param {string} rootDir the repository root
+ * @returns {string[]} paths relative to `rootDir`, in a fixed order
+ */
+export function aiContextFilesAt(rootDir) {
+  const references = existsSync(join(rootDir, SKILL_REFERENCES))
+    ? readdirSync(join(rootDir, SKILL_REFERENCES))
+        .filter((name) => name.endsWith(".md"))
+        .sort()
+        .map((name) => `${SKILL_REFERENCES}/${name}`)
+    : []
+  return [
+    ...REQUIRED,
+    ...OPTIONAL.filter((file) => existsSync(join(rootDir, file))),
+    ...references,
+  ]
+}
+
+export const AI_CONTEXT_FILES = aiContextFilesAt(
+  join(dirname(fileURLToPath(import.meta.url)), "..")
+)
+
+/**
+ * The Claude Code plugin marketplace at the repository root. Each plugin it
+ * lists is a directory in this repository holding `.claude-plugin/plugin.json`
+ * and the skill it installs. Optional: the v4 line has none until DX3.
+ */
+export const CLAUDE_MARKETPLACE = ".claude-plugin/marketplace.json"
+
+/**
+ * Plugin manifests whose `version` is the release lane's version.
+ *
+ * A JSON `"version"` line names no package, so the line-based sweep in
+ * `sync-ai-context-versions.js` cannot rewrite it; `release.js` sets these
+ * with `syncPluginManifestVersions` instead, and `check-ai-context.js` fails
+ * when one differs from `@ic-reactor/react`. Claude Code installs a new copy
+ * of a plugin only when this version changes. Empty until DX3 adds the skill.
+ */
+export const RUNTIME_PLUGIN_MANIFESTS = []