@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/scripts/verify-typescript-floor.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Do the published declarations compile with the oldest TypeScript we support?
+ *
+ * The packages build with the newest TypeScript, but a consumer compiles their
+ * emitted `.d.ts` files, and those of their dependencies, with its own. Those
+ * declarations need TypeScript 5.7: they use generic typed arrays such as
+ * `Uint8Array<ArrayBuffer>`, which 5.7 introduced, and older compilers reject
+ * them with TS2315 "Type 'Uint8Array' is not generic". The docs said
+ * "TypeScript 5+" while every check in CI compiled with the newest TypeScript,
+ * so nothing noticed (#591).
+ *
+ * This writes a consumer, in a temporary directory, that imports every public
+ * entry point of the packages below (each subpath of their `exports` maps
+ * that a consumer can import),
+ * and compiles it with TYPESCRIPT_FLOOR, `strict` and `skipLibCheck: false`:
+ * once with `moduleResolution: "bundler"` and once with `"node16"`, for each
+ * of its programs. The consumer reaches the packages through symlinks, so their
+ * declarations resolve their own dependencies from the workspace install, at
+ * the lockfile's versions.
+ *
+ * It reads the declarations `pnpm build` wrote to `packages/<name>/dist`, so
+ * build first. `pnpm verify:peer-floors` runs it.
+ *
+ * Usage
+ *   node scripts/verify-typescript-floor.js [--keep]
+ *
+ *   --keep   leave the consumer directory in place (debugging)
+ */
+import { spawnSync } from "node:child_process"
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, join, normalize } from "node:path"
+import { tmpdir } from "node:os"
+import { fileURLToPath } from "node:url"
+import { readJson, run, writeJson } from "./lib/io.mjs"
+import { publicSubpaths, specifierOf } from "./lib/package-exports.mjs"
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..")
+const keep = process.argv.includes("--keep")
+
+/**
+ * The oldest TypeScript the packages support, the first stable 5.7 release.
+ * The docs name it as well, so change them with it: the badges in README.md
+ * and packages/core/README.md, and the support table in
+ * docs/src/content/docs/versioning.mdx.
+ */
+const TYPESCRIPT_FLOOR = "5.7.2"
+
+/**
+ * The packages whose declarations are compiled, by directory under packages/,
+ * in one program for each entry. The Vite plugin's declarations import Vite's,
+ * which reference Node's types (`/// <reference types="node" />`). In one
+ * program with core and react, those types would reach their declarations too,
+ * and `types: []` would no longer catch one that uses Node's globals (#980).
+ */
+const PROGRAMS = { app: ["core", "react"], "vite-plugin": ["vite-plugin"] }
+
+/**
+ * The tsconfig the installation guide recommends, with `skipLibCheck` off so
+ * the declarations are checked. `types: []` keeps out every `@types` package
+ * the imports do not reach, so a declaration that uses Node's globals without
+ * importing them fails here, as it would in a browser app.
+ */
+const COMPILER_OPTIONS = {
+  strict: true,
+  skipLibCheck: false,
+  noEmit: true,
+  target: "ES2020",
+  lib: ["ES2020", "DOM", "DOM.Iterable"],
+  esModuleInterop: true,
+  types: [],
+}
+
+/**
+ * The resolution modes the packages support, as verify-package-artifacts.mjs
+ * checks them with attw's node16 profile. `node10` is not one: it ignores
+ * `exports`, so the `@icp-sdk/core` subpaths the declarations import do not
+ * resolve.
+ */
+const MODES = {
+  bundler: { module: "ESNext", moduleResolution: "Bundler" },
+  node16: { module: "Node16", moduleResolution: "Node16" },
+}
+
+/**
+ * The specifier of every public entry point: each subpath of the `exports` map
+ * except `./package.json` and one mapped to `null` (`publicSubpaths`). A
+ * pattern such as `./*` cannot be listed, so it fails here instead of going
+ * unchecked.
+ */
+function entryPoints(manifest) {
+  return publicSubpaths(manifest).map((subpath) => {
+    const specifier = specifierOf(manifest.name, subpath)
+    if (subpath.includes("*")) {
+      throw new Error(`Cannot list the entry points matching "${specifier}"`)
+    }
+    return specifier
+  })
+}
+
+/** Every file an `exports` value names under a `types` condition. */
+function typesTargets(value) {
+  if (value === null || typeof value !== "object") return []
+  return Object.entries(value).flatMap(([key, target]) =>
+    key === "types" && typeof target === "string"
+      ? [target]
+      : typesTargets(target)
+  )
+}
+
+/**
+ * Writes the consumer, a `<program>.ts` and a `tsconfig.<program>.<mode>.json`
+ * for each program and mode, and returns the specifiers each program imports.
+ */
+function writeConsumer(consumer, links) {
+  writeJson(join(consumer, "package.json"), { private: true, type: "module" })
+  return Object.fromEntries(
+    Object.entries(PROGRAMS).map(([program, dirs]) => [
+      program,
+      writeProgram(consumer, links, program, dirs),
+    ])
+  )
+}
+
+/** Writes one program of the consumer and returns the specifiers it imports. */
+function writeProgram(consumer, links, program, dirs) {
+  const specifiers = []
+  for (const dir of dirs) {
+    const packageDir = join(rootDir, "packages", dir)
+    const manifest = readJson(join(packageDir, "package.json"))
+    const declared = [manifest.types, ...typesTargets(manifest.exports)]
+      .filter((file) => file !== undefined)
+      .map((file) => normalize(file))
+    const missing = [...new Set(declared)].filter(
+      (file) => !existsSync(join(packageDir, file))
+    )
+    if (missing.length > 0) {
+      throw new Error(
+        `${manifest.name} is not built (no ${missing.join(", ")}). Run \`pnpm build\` first.`
+      )
+    }
+    const link = join(consumer, "node_modules", manifest.name)
+    mkdirSync(dirname(link), { recursive: true })
+    symlinkSync(packageDir, link, "dir")
+    links.push(link)
+    specifiers.push(...entryPoints(manifest))
+  }
+
+  const names = specifiers.map((_, i) => `entry${i}`)
+  writeFileSync(
+    join(consumer, `${program}.ts`),
+    [
+      ...specifiers.map(
+        (specifier, i) => `import * as ${names[i]} from "${specifier}"`
+      ),
+      `export { ${names.join(", ")} }`,
+      "",
+    ].join("\n")
+  )
+  for (const [mode, options] of Object.entries(MODES)) {
+    writeJson(join(consumer, `tsconfig.${program}.${mode}.json`), {
+      compilerOptions: { ...COMPILER_OPTIONS, ...options },
+      files: [`${program}.ts`],
+    })
+  }
+  return specifiers
+}
+
+const consumer = mkdtempSync(join(tmpdir(), "typescript-floor-"))
+const links = []
+let ok = false
+try {
+  const programs = writeConsumer(consumer, links)
+  console.log(`\n▶ TypeScript ${TYPESCRIPT_FLOOR}`)
+  for (const [program, specifiers] of Object.entries(programs)) {
+    console.log(`  ${program}: ${specifiers.join(", ")}`)
+  }
+
+  // Run from the consumer, outside the workspace, so npx cannot pick up the
+  // workspace's own TypeScript, and confirm which compiler it runs. Under
+  // `pnpm verify:peer-floors`, npm warns about every npm_config_* variable
+  // pnpm exports; `--loglevel=error` keeps those warnings out of the output.
+  const tsc = [
+    "--yes",
+    "--loglevel=error",
+    "--package",
+    `typescript@${TYPESCRIPT_FLOOR}`,
+    "tsc",
+  ]
+  const version = spawnSync("npx", [...tsc, "--version"], {
+    cwd: consumer,
+    encoding: "utf8",
+  })
+  const found = (version.stdout ?? "").trim()
+  if (found !== `Version ${TYPESCRIPT_FLOOR}`) {
+    throw new Error(
+      `npx did not run TypeScript ${TYPESCRIPT_FLOOR}: ${found || version.stderr || version.error?.message}`
+    )
+  }
+  console.log(found)
+  const failed = Object.keys(programs).flatMap((program) =>
+    Object.keys(MODES)
+      .filter((mode) => {
+        console.log(`  ${program}, moduleResolution: ${mode}`)
+        const project = `tsconfig.${program}.${mode}.json`
+        return !run("npx", [...tsc, "--project", project], consumer)
+      })
+      .map((mode) => `${program} with moduleResolution: ${mode}`)
+  )
+  if (failed.length > 0) {
+    throw new Error(
+      `The declarations do not compile with TypeScript ${TYPESCRIPT_FLOOR} (${failed.join("; ")})`
+    )
+  }
+  ok = true
+  console.log(
+    `✔ The declarations compile with TypeScript ${TYPESCRIPT_FLOOR} (moduleResolution: ${Object.keys(MODES).join(", ")})`
+  )
+} catch (error) {
+  console.error(`✖ ${error.message}`)
+} finally {
+  if (keep) {
+    console.log(`  consumer kept at ${consumer}`)
+  } else {
+    // Unlink the package links first: they point into packages/, and nothing
+    // below should ever walk into them.
+    for (const link of links) unlinkSync(link)
+    rmSync(consumer, { recursive: true, force: true })
+  }
+}
+process.exit(ok ? 0 : 1)

package/skill-packages/ic-reactor/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ic-reactor
+description: >-
+  Write, review and fix app code that calls Internet Computer (ICP) canisters
+  with ic-reactor 4 (@ic-reactor/core, @ic-reactor/react,
+  @ic-reactor/vite-plugin) over a module generated by @meantjs/cli, in
+  React or plain TypeScript. Use when the project depends on an @ic-reactor/*
+  package at version 4, or the user asks to set up a canister client
+  (createClient, ReactorProvider), read or write a canister with TanStack Query
+  (client.queryOptions, client.mutationOptions), sign users in (useAuth),
+  decide whether a failed call may have executed (ReactorError, kind,
+  mayHaveExecuted), parse or show token amounts (parseUnits, formatUnits),
+  generate the module from a .did file, or test canister code. Not for
+  changing the ic-reactor library itself.
+license: MIT
+---
+
+# ic-reactor 4 in an app
+
+This skill is a workflow. The API and its rules are in one guide that ships
+with the package, `node_modules/@ic-reactor/core/llms.txt`: read it before
+writing code, and follow it over anything here, including your memory of
+earlier ic-reactor versions (their names are gone in 4).
+
+This skill describes these versions:
+
+- `@ic-reactor/core`: `4.1.1`
+- `@ic-reactor/react`: `4.1.1`
+- `@ic-reactor/vite-plugin`: `4.1.1`
+
+## Workflow
+
+1. **Read the installed guide.** Its `Applies to` line names the release it
+   describes; when that differs from the list above, the installed guide wins.
+2. **Install the exact peers.** `@ic-reactor/core` with `@icp-sdk/core` and
+   `@tanstack/query-core`; for React, `@ic-reactor/react` (at exactly core's
+   version), `@tanstack/react-query` and `react`, with `@tanstack/query-core`
+   at the exact version `@tanstack/react-query` depends on, so that
+   `npm ls @tanstack/query-core` shows one copy; `@icp-sdk/auth` for Internet
+   Identity sign-in. `@meantjs/schema` must be the exact version
+   `@ic-reactor/core` lists in its `peerDependencies`, and the generator
+   `@meantjs/cli` the exact version `@ic-reactor/vite-plugin` lists:
+   install both with `--save-exact`. The `@ic-reactor/*` packages are on npm's
+   `latest` dist-tag: install them bare, and never pin a 3.x version, whose
+   names this guide does not describe.
+3. **Generate the module** from each canister's `.did`, with
+   `npx @meantjs/cli gen <file>.did -o src/generated`, or with the Vite
+   plugin, which regenerates on change:
+
+   ```ts
+   // vite.config.ts
+   import { defineConfig } from "vite"
+   import { icReactor } from "@ic-reactor/vite-plugin"
+
+   export default defineConfig({
+     plugins: [
+       icReactor({
+         canisters: {
+           ledger: { didFile: "did/icrc1.did", outDir: "src/generated" },
+         },
+       }),
+     ],
+   })
+   ```
+
+   The module is named after the `.did` file: for `icrc1.did` both write
+   `src/generated/icrc1.ts`, which the guide imports as `./generated/icrc1`.
+   Without `outDir` the plugin writes to `src/canisters/`, and the imports
+   must follow. Never edit the generated file; take method names and value
+   shapes from its `type Actor`, and never guess them. In CI, `npx @meantjs/cli gen ... --check`
+   fails on a stale module.
+
+4. **Create one client** with `createClient({ network, identity | auth })`:
+   one per browser tab, or one per request on a server. Choose the network and
+   the caller as the guide's Setup section says, including its rule for an
+   identity that may be anonymous.
+5. **In React**, render `ReactorProvider` with a client factory around the
+   tree that calls canisters, and read the client and the caller with
+   `useClient()` and `useAuth()`.
+6. **Read and write** with `useQuery(client.queryOptions(...))` and
+   `useMutation(client.mutationOptions(...))`, or call the canister's methods
+   directly outside React. Build options in render from that render's
+   `useClient()`, never from a module-scope client, and add neither `retry` to
+   a write nor data carried across keys. Read what decides where value goes or
+   what a person approves (a recipient, a deposit address, an allowance)
+   through a `certified: true` canister, and the rest plainly.
+7. **Handle failures** by `isReactorError(error)`, then `kind` and
+   `mayHaveExecuted`: when it is `true`, tell the user the outcome is unknown
+   and re-read; never re-send by hand. A write that timed out (`timeoutMs`,
+   code `"timeout"`) after its request went out is such an unknown outcome,
+   and a `cancelled` with that code is a real timeout to show, not ignore.
+   Only a method the canister deduplicates (an ICRC-1 transfer with
+   `created_at_time`) may offer the same argument again, through
+   `client.resendOf(error, canister, method, { dedupedBy })`.
+   After a direct call, use
+   `isReactorError(error, canister, method)` to read a typed `err`; never cast it.
+8. **Test** through `createTestClient()` from `@ic-reactor/core/testing`, a
+   real client over an in-memory replica, not with stubbed calls; then run the
+   app's type check and tests.
+
+## Before you finish
+
+Check the code against the guide's "Do not" list, item by item.

package/stack.json

@@ -0,0 +1,8 @@
+{
+  "$comment": "The Meant release this branch is tested against. `pnpm check:stack` holds the tree to this file. To repin, change a version here and run `pnpm sync:stack` and `pnpm install`; CONTRIBUTING.md has the whole repin.",
+  "meant": {
+    "@meantjs/schema": "0.6.0",
+    "@meantjs/cli": "0.5.1"
+  },
+  "frozen": ["evals/"]
+}

package/tsconfig.base.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "noImplicitAny": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./packages/core" },
+    { "path": "./packages/react" },
+    { "path": "./packages/vite-plugin" }
+  ]
+}