envio 3.15.0 → 3.16.0-subgraph

package/src/subgraph/scope.ts

@@ -0,0 +1,176 @@
+import type { AggregationDef } from "./aggregations.ts";
+import type { RegisterSlot } from "./register-slots.ts";
+
+/** What a wrapper is doing when it runs the mapping. */
+export type Mode = "handler" | "register";
+
+export type SubgraphSchema = {
+  timestampFields: Record<string, string[]>;
+  entityListFields: Record<string, string[]>;
+  entityFields: Record<string, string[]>;
+  entityRefFields: Record<string, string[]>;
+  /** Each field as the subgraph schema declares it, which is what a mapping reads. */
+  entityFieldTypes: Record<
+    string,
+    Record<
+      string,
+      {
+        kind: string;
+        target?: string;
+        derivedFrom?: string;
+        list: boolean;
+        required?: boolean;
+        /** `[String]`: stored as a list of non-null elements. */
+        nullableElements?: boolean;
+      }
+    >
+  >;
+  /** The context accessor envio generated for each entity, by schema name. */
+  entityAccessors: Record<string, string>;
+  /** `@entity(timeseries: true)` types: saved with an automatic id and timestamp. */
+  timeseriesEntities: string[];
+  /** `@entity(immutable: true, skipDuplicates: true)` types: an id stored in an earlier block keeps its first write. */
+  skipDuplicateEntities: string[];
+  aggregations: AggregationDef[];
+};
+
+/** One event's register pass while it runs. */
+export type RegisterPass = {
+  chainId: number;
+  position: number;
+  done: Promise<void>;
+  settled: boolean;
+  /** The register-store keys it missed, so later passes can wait on it. */
+  missed: string[];
+  /** A read missed while an earlier pass of its chain was still running. */
+  provisional: boolean;
+};
+
+export type Scope = {
+  /** envio's handler or contractRegister context. */
+  context: any;
+  event: any;
+  mode: Mode;
+  schema: SubgraphSchema;
+  dataSource: {
+    name: string;
+    address: string;
+    chainId: number;
+    network: string;
+    /** The manifest's `context` entries, as `dataSource.context()` serves them. */
+    context: Record<string, { type: string; data: string }>;
+    /** A static data source without `source.address`: `address` is the emitter's, `dataSource.address()` none. */
+    wildcard?: boolean;
+  };
+  /** Addresses already registered this round, so replays stay idempotent. */
+  registered: Set<string>;
+  /**
+   * Host results the register pass has resolved, keyed by effect and input.
+   * The register pass has no envio context to run effects through, so it
+   * replays the mapping itself and answers from here (§5, register mode).
+   */
+  resolved?: Map<string, { value?: unknown; error?: unknown }>;
+  /** Lookups the current register round is waiting on. */
+  awaiting?: Promise<unknown>[];
+  /** The block a contract call is evaluated against, as graph-node does. */
+  blockNumber: number;
+  /** The block's time in seconds: what a timeseries entity is stamped with. */
+  blockSeconds?: () => number | string;
+  /** Timeseries entities saved so far by this run of the handler. */
+  timeseriesSequence?: number;
+  /** Where this run's timeseries ids start in its block's id sequence. */
+  timeseriesBase?: number;
+  /** Where the event sits in its chain, for what the register pass may read. */
+  position?: number;
+  /** The register round's own writes, kept only once the round completes. */
+  writes?: Map<string, Record<string, unknown> | null>;
+  /** This register pass, as other passes of its batch wait on it. */
+  pass?: RegisterPass;
+  /** Entities this pass already waited on another pass for: it waits once. */
+  waitedKeys?: Set<string>;
+  /** The register pass's slot (`register-slots.ts`), held while it runs. */
+  slot?: RegisterSlot;
+  /** The round's wait includes an earlier pass: the slot is given back for it. */
+  waitsOnPass?: boolean;
+  /** The mapping module, so `ipfs.map` can reach the callback it names. */
+  mappingExports: Record<string, any>;
+  /** Set when the scope is a file data source's handler. */
+  file?: FileScope;
+  /** The block handler this run is, when it has no register pass of its own. */
+  blockHandler?: string;
+  /** File templates this run created, keyed to dedupe a replayed mapping. */
+  fileCreates?: Map<string, FileCreate>;
+  /** Register mode: instances this pass created of templates with a `once` handler. */
+  templateOnces?: { template: string; address: string }[];
+};
+
+/** A `DataSourceTemplate.create` of a file template, waiting for its file. */
+export type FileCreate = {
+  template: string;
+  /** The CID or Arweave transaction id the mapping passed. */
+  source: string;
+  /** The `DataSourceContext` of `createWithContext`, if there was one. */
+  context?: unknown;
+};
+
+/** What distinguishes a file data source's handler run from a chain one. */
+export type FileScope = {
+  kind: "ipfs" | "arweave";
+  /**
+   * The manifest's `entities` list. graph-node lets a file data source touch
+   * only these types, and refuses any other, read or write.
+   */
+  entities: Set<string>;
+  /**
+   * What this run has written, by entity type and id. graph-node keys an entity
+   * by its causality region too, so a file data source can't see a chain
+   * entity (or another file's) even of the same type and id: a read answers
+   * from here only.
+   */
+  written: Set<string>;
+  context?: unknown;
+};
+
+// A mapping runs synchronously from start to end of a round, so the scope is a
+// plain variable rather than an AsyncLocalStorage: in this Node, a live
+// AsyncLocalStorage installs promise hooks that tax every promise the indexer
+// makes (~4% of indexing CPU).
+let current: Scope | undefined;
+
+export function runInScope<T>(scope: Scope, fn: () => T): T {
+  const previous = current;
+  current = scope;
+  try {
+    return fn();
+  } finally {
+    current = previous;
+  }
+}
+
+/**
+ * A mapping module's top level runs during its import, after `import()` has
+ * returned. Mappings are imported one at a time, so the scope is held until
+ * the import settles.
+ */
+export async function runInScopeUntilSettled<T>(scope: Scope, fn: () => Promise<T>): Promise<T> {
+  const previous = current;
+  current = scope;
+  try {
+    return await fn();
+  } finally {
+    current = previous;
+  }
+}
+
+export function currentScope(): Scope {
+  const scope = current;
+  if (!scope) {
+    throw new Error(
+      "A graph-ts API was called outside of a mapping handler. Envio Subgraph " +
+        "runs mappings inside a scope that carries the event and the store; " +
+        "calling into graph-ts from module top-level or from a detached " +
+        "callback escapes it.",
+    );
+  }
+  return scope;
+}

package/src/subgraph/stats.ts

@@ -0,0 +1,42 @@
+/**
+ * `ENVIO_SUBGRAPH_SYNC_STATS=1` counts how often the sync bridge replays a
+ * mapping (§5), per phase, and prints the totals as one `SGSTATS {json}` line
+ * on stderr every 30 s and at exit. A preload round that suspends is the
+ * batching working; an execute round that suspends is a database round trip
+ * the batch waits on, one event at a time.
+ */
+
+const enabled = process.env.ENVIO_SUBGRAPH_SYNC_STATS === "1";
+
+type PhaseStats = { runs: number; rounds: number; maxRounds: number; byRounds: Record<string, number> };
+const makePhase = (): PhaseStats => ({ runs: 0, rounds: 0, maxRounds: 0, byRounds: {} });
+const stats = { preload: makePhase(), execute: makePhase() };
+
+function record(phase: PhaseStats, rounds: number) {
+  phase.runs++;
+  phase.rounds += rounds;
+  if (rounds > phase.maxRounds) phase.maxRounds = rounds;
+  const bucket = rounds >= 5 ? "5+" : String(rounds);
+  phase.byRounds[bucket] = (phase.byRounds[bucket] ?? 0) + 1;
+}
+
+if (enabled) {
+  const print = () => process.stderr.write(`SGSTATS ${JSON.stringify(stats)}\n`);
+  setInterval(print, 30_000).unref();
+  process.on("exit", print);
+}
+
+/** `context.runSync(body)`, counting the rounds it took when stats are on. */
+export async function runSyncCounted(context: any, body: () => void): Promise<void> {
+  if (!enabled) return context.runSync(body);
+  let rounds = 0;
+  const isPreload = context.isPreload;
+  try {
+    await context.runSync(() => {
+      rounds++;
+      body();
+    });
+  } finally {
+    record(isPreload ? stats.preload : stats.execute, rounds);
+  }
+}

package/src/subgraph/template-instances.ts

@@ -0,0 +1,66 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+type Instance = { address: string; block: number };
+
+const instances = new Map<string, Instance[]>();
+let loaded = false;
+
+function file(): string {
+  return path.join(process.cwd(), ".envio", "subgraph-template-instances.jsonl");
+}
+
+const keyOf = (chainId: number, template: string) => `${chainId}:${template}`;
+
+function add(key: string, address: string, block: number): boolean {
+  const list = instances.get(key) ?? [];
+  const known = list.find((instance) => instance.address === address);
+  if (known) {
+    if (known.block === block) return false;
+    known.block = block;
+    return true;
+  }
+  list.push({ address, block });
+  instances.set(key, list);
+  return true;
+}
+
+function load() {
+  if (loaded) return;
+  loaded = true;
+  try {
+    for (const line of readFileSync(file(), "utf8").split("\n")) {
+      if (!line) continue;
+      const { key, address, block } = JSON.parse(line);
+      add(key, address, block);
+    }
+  } catch {
+    // none saved yet
+  }
+}
+
+/**
+ * A template instance and the block it was created in, which its block
+ * handlers run from. envio keeps the address of a created data source and not
+ * the block graph-node starts its triggers at, so the block is kept here, in
+ * the project's `.envio` directory too: a restart loads the addresses from
+ * storage and no register pass runs for the old creations.
+ */
+export function rememberInstance(chainId: number, template: string, address: string, block: number) {
+  load();
+  const key = keyOf(chainId, template);
+  const lower = address.toLowerCase();
+  if (!add(key, lower, block)) return;
+  try {
+    mkdirSync(path.dirname(file()), { recursive: true });
+    appendFileSync(file(), JSON.stringify({ key, address: lower, block }) + "\n");
+  } catch {
+    // in memory still serves this run
+  }
+}
+
+/** The instances of `template` created at or before `block`, with their creation blocks. */
+export function instancesAt(chainId: number, template: string, block: number): Instance[] {
+  load();
+  return (instances.get(keyOf(chainId, template)) ?? []).filter((instance) => instance.block <= block);
+}

package/src/subgraph/toolchain.ts

@@ -0,0 +1,327 @@
+/**
+ * The pieces of a subgraph's toolchain envio fetches itself when the project's
+ * own `node_modules` can't supply them.
+ *
+ * graph-node never installs a repo's npm dependencies at index time, it runs
+ * compiled WASM. A team moving a subgraph expects one command to work in the
+ * repo as it is, and a repo whose full install fails (a dead git dependency in
+ * an old graph-cli lockfile, a vanished gluegun fork, ETARGET) would otherwise
+ * stop before the first line of a mapping ran. Only two things are needed:
+ *
+ *  - the packages the mappings actually import (`@openzeppelin/subgraphs`,
+ *    `@protofire/subgraph-toolkit`, ...), found by walking the mapping import
+ *    graph, at the versions the repo's lockfile or package.json names;
+ *  - a graph-cli, to run `graph codegen`, at a version that installs.
+ *
+ * Both are installed with npm into a cache directory of envio's own, away from
+ * the repo, with no lifecycle scripts, skipping git, file and workspace
+ * dependencies and every devDependency the mappings don't import.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import { info, warn } from "./log.ts";
+
+/** Where fetched packages live: `ENVIO_SUBGRAPH_CACHE_DIR`, else the user's cache. */
+export function cacheDir(): string {
+  return (
+    process.env.ENVIO_SUBGRAPH_CACHE_DIR ||
+    path.join(process.env.XDG_CACHE_HOME || path.join(homedir(), ".cache"), "envio", "subgraph")
+  );
+}
+
+/**
+ * npm into `dir` (a prefix with its own node_modules), atomically: installed
+ * beside it, then renamed, so an interrupted install never leaves a half
+ * cache that looks complete.
+ */
+async function npmInstallInto(dir: string, specs: string[]): Promise<void> {
+  if (existsSync(path.join(dir, ".envio-installed"))) return;
+  const staging = `${dir}.tmp-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  writeFileSync(path.join(staging, "package.json"), JSON.stringify({ name: "envio-subgraph-cache", private: true }));
+  const output: string[] = [];
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(
+      "npm",
+      [
+        "install",
+        "--no-audit",
+        "--no-fund",
+        "--no-package-lock",
+        "--ignore-scripts",
+        "--legacy-peer-deps",
+        "--loglevel=error",
+        ...specs,
+      ],
+      { cwd: staging, env: process.env },
+    );
+    child.stdout.on("data", (chunk) => output.push(String(chunk)));
+    child.stderr.on("data", (chunk) => output.push(String(chunk)));
+    child.on("error", reject);
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`npm install ${specs.join(" ")} exited with ${code}\n${output.join("").slice(-1500)}`)),
+    );
+  }).catch((error) => {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  });
+  writeFileSync(path.join(staging, ".envio-installed"), specs.join("\n"));
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(path.dirname(dir), { recursive: true });
+  renameSync(staging, dir);
+}
+
+// --- what the repo declares -------------------------------------------------
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+/** A package.json spec npm can fetch from the registry: a version or range, not a git, file, link or workspace one. */
+function registrySpec(spec: unknown): string | null {
+  if (typeof spec !== "string" || spec === "" || spec === "*" || spec === "latest") return null;
+  if (/^(?:git|github|file|link|workspace|portal|patch|http|https|npm:|[^@\s]+\/[^@\s]+$)/.test(spec) || spec.includes("://")) {
+    return null;
+  }
+  return spec;
+}
+
+function readJson(file: string): any {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The version a lockfile in `dir` resolved `name` to: npm, yarn (1 and berry) or pnpm. */
+function lockedVersion(dir: string, name: string): string | null {
+  const npmLock = readJson(path.join(dir, "package-lock.json"));
+  if (npmLock) {
+    const version = npmLock.packages?.[`node_modules/${name}`]?.version ?? npmLock.dependencies?.[name]?.version;
+    if (EXACT_VERSION.test(version ?? "")) return version;
+  }
+  const read = (file: string) => (existsSync(file) ? readFileSync(file, "utf8") : null);
+  const yarn = read(path.join(dir, "yarn.lock"));
+  if (yarn) {
+    for (const block of yarn.split(/\n\s*\n/)) {
+      const header = block.split("\n").find((line) => line !== "" && !line.startsWith("#"));
+      if (!header) continue;
+      const entries = header.replace(/:\s*$/, "").split(/,\s*/).map((entry) => entry.trim().replace(/^"|"$/g, ""));
+      if (!entries.some((entry) => entry.startsWith(`${name}@`))) continue;
+      const version = block.match(/^\s+version:?\s+"?([^"\s]+)"?/m)?.[1];
+      if (version && EXACT_VERSION.test(version)) return version;
+    }
+  }
+  const pnpm = read(path.join(dir, "pnpm-lock.yaml"));
+  if (pnpm) {
+    const version = pnpm.match(new RegExp(`^\\s+'?/?${escapeRegExp(name)}@(\\d[^:(')\\s]*)`, "m"))?.[1];
+    if (version && EXACT_VERSION.test(version)) return version;
+  }
+  return null;
+}
+
+/**
+ * The version of `name` to fetch: the lockfile's, else package.json's range,
+ * from the project's directory up through the workspace root; null for latest.
+ */
+export function declaredVersion(root: string, name: string): string | null {
+  const directories: string[] = [];
+  for (let dir = path.resolve(root); ; dir = path.dirname(dir)) {
+    directories.push(dir);
+    if (path.dirname(dir) === dir) break;
+  }
+  for (const dir of directories) {
+    const locked = lockedVersion(dir, name);
+    if (locked) return locked;
+  }
+  for (const dir of directories) {
+    const manifest = readJson(path.join(dir, "package.json"));
+    const spec = registrySpec(
+      manifest?.dependencies?.[name] ??
+        manifest?.devDependencies?.[name] ??
+        manifest?.peerDependencies?.[name] ??
+        manifest?.optionalDependencies?.[name],
+    );
+    if (spec) return spec;
+  }
+  return null;
+}
+
+// --- the packages the mappings import -----------------------------------------
+
+const BARE_IMPORT = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["']([@\w][^"'\s]*)["']/g;
+/** A name npm would accept: lowercase, optionally scoped. */
+const NPM_NAME = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
+const RELATIVE_IMPORT = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["'](\.\.?\/[^"']*)["']/g;
+const BUILTINS = new Set(builtinModules);
+/** Never fetched: the shim replaces them. */
+const SHIMMED = new Set(["@graphprotocol/graph-ts", "matchstick-as"]);
+const MAX_SCANNED_FILES = 2_000;
+
+function packageName(specifier: string): string | null {
+  if (specifier.startsWith("node:") || specifier.startsWith("#")) return null;
+  const parts = specifier.split("/");
+  const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+  if (!name || !NPM_NAME.test(name) || BUILTINS.has(name) || SHIMMED.has(name)) return null;
+  return name;
+}
+
+/** Whether Node would find `name` from `fromDir`: a node_modules there or in any parent. */
+function resolvableFrom(fromDir: string, name: string): boolean {
+  for (let dir = path.resolve(fromDir); ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, "node_modules", name, "package.json"))) return true;
+    if (path.dirname(dir) === dir) return false;
+  }
+}
+
+/**
+ * The npm packages the mappings import that the project can't resolve, found by
+ * walking the mapping files' relative imports. `generated/` is not walked: it
+ * imports only graph-ts.
+ */
+export function missingMappingPackages(root: string, mappingFiles: string[]): string[] {
+  const queue = [...new Set(mappingFiles)].map((file) => path.resolve(root, file));
+  const seen = new Set(queue);
+  const missing = new Set<string>();
+  for (let index = 0; index < queue.length && index < MAX_SCANNED_FILES; index++) {
+    const file = queue[index];
+    let source: string;
+    try {
+      source = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    for (const [, specifier] of source.matchAll(BARE_IMPORT)) {
+      const name = packageName(specifier);
+      if (name && !resolvableFrom(path.dirname(file), name)) missing.add(name);
+    }
+    for (const [, specifier] of source.matchAll(RELATIVE_IMPORT)) {
+      const target = path.resolve(path.dirname(file), specifier);
+      for (const candidate of [target, `${target}.ts`, path.join(target, "index.ts")]) {
+        if (!seen.has(candidate) && existsSync(candidate) && statSync(candidate).isFile()) {
+          seen.add(candidate);
+          queue.push(candidate);
+          break;
+        }
+      }
+    }
+  }
+  return [...missing].sort();
+}
+
+/**
+ * Fetches `names` into the cache, each at the version the project declares,
+ * falling back to the latest when that version is gone (ETARGET). Returns the
+ * `node_modules` directory holding them, or null when nothing installed. A
+ * package that can't be fetched at all (a workspace package that isn't on the
+ * registry) is left out, so the mapping that imports it reports it by name.
+ */
+export async function fetchMappingPackages(root: string, names: string[]): Promise<string | null> {
+  if (names.length === 0) return null;
+  const specs = names.map((name) => {
+    const version = declaredVersion(root, name);
+    return version ? `${name}@${version}` : name;
+  });
+  const key = createHash("sha1").update(specs.join("\n")).digest("hex").slice(0, 12);
+  const dir = path.join(cacheDir(), "packages", key);
+  const modules = path.join(dir, "node_modules");
+  if (existsSync(path.join(dir, ".envio-installed"))) return modules;
+
+  info(`Envio Subgraph is fetching ${specs.join(", ")} into ${dir}: the project's own node_modules lacks ${names.length === 1 ? "it" : "them"}.`);
+  try {
+    await npmInstallInto(dir, specs);
+    return modules;
+  } catch {
+    // One bad spec fails the whole install; find which.
+  }
+  const installed: string[] = [];
+  for (const [index, spec] of specs.entries()) {
+    const one = path.join(cacheDir(), "packages", createHash("sha1").update(spec).digest("hex").slice(0, 12));
+    for (const attempt of spec === names[index] ? [spec] : [spec, names[index]]) {
+      try {
+        await npmInstallInto(one, [attempt]);
+        installed.push(one);
+        break;
+      } catch (error) {
+        if (attempt === names[index]) {
+          warn(`Envio Subgraph could not fetch ${names[index]} (${String(error).split("\n")[0]}); a mapping importing it will fail by name.`);
+        }
+      }
+    }
+  }
+  if (installed.length === 0) return null;
+  // Merge the per-package installs into one node_modules, so resolution has a single place to look.
+  const merged = path.join(dir, "node_modules");
+  mkdirSync(merged, { recursive: true });
+  for (const one of installed) {
+    for (const entry of readdirSync(path.join(one, "node_modules"))) {
+      cpSync(path.join(one, "node_modules", entry), path.join(merged, entry), { recursive: true, force: false });
+    }
+  }
+  writeFileSync(path.join(dir, ".envio-installed"), specs.join("\n"));
+  return modules;
+}
+
+// --- graph-cli ----------------------------------------------------------------
+
+/**
+ * The newest graph-cli whose own dependencies still install, and the one the
+ * generated code of older subgraphs is closest to: 0.51 has none of the
+ * dead git pins that 0.45 and older do (hugomrdias/concat-stream, the
+ * edgeandnode/gluegun fork) and still accepts a schema graph-cli 0.9x rejects
+ * (`@entity` without `immutable`, nullable list members are the next gate).
+ */
+export const OLDEST_INSTALLABLE_GRAPH_CLI = "0.51.0";
+/** For manifests newer than 0.51 reads (specVersion 1.x, indexerHints). */
+export const NEWEST_GRAPH_CLI = "0.98.1";
+
+/** The first x.y.z in a spec, as numbers. */
+function leadingVersion(spec: string): [number, number, number] | null {
+  const match = spec.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+function atLeast(version: [number, number, number], minimum: [number, number, number]): boolean {
+  for (let index = 0; index < 3; index++) {
+    if (version[index] !== minimum[index]) return version[index] > minimum[index];
+  }
+  return true;
+}
+
+/**
+ * graph-cli versions to try, best first: the project's own when it is new
+ * enough to install (a version the repo's author ran), then the two pins.
+ */
+export function graphCliVersions(root: string): string[] {
+  const versions: string[] = [];
+  const declared = declaredVersion(root, "@graphprotocol/graph-cli");
+  const parsed = declared ? leadingVersion(declared) : null;
+  if (declared && parsed && atLeast(parsed, [0, 50, 0])) versions.push(declared);
+  versions.push(OLDEST_INSTALLABLE_GRAPH_CLI, NEWEST_GRAPH_CLI);
+  return [...new Set(versions)];
+}
+
+/** The package directory of `@graphprotocol/graph-cli@version` in the cache, fetching it first if need be. */
+export async function fetchGraphCli(version: string): Promise<string | null> {
+  const dir = path.join(cacheDir(), "graph-cli", version.replace(/[^0-9A-Za-z.^~<>=-]/g, "_"));
+  const packageDir = path.join(dir, "node_modules", "@graphprotocol", "graph-cli");
+  if (!existsSync(path.join(dir, ".envio-installed"))) {
+    info(`Envio Subgraph is fetching @graphprotocol/graph-cli@${version} into ${dir} to generate code: the project's own isn't usable.`);
+    try {
+      await npmInstallInto(dir, [`@graphprotocol/graph-cli@${version}`]);
+    } catch (error) {
+      warn(`Envio Subgraph could not fetch @graphprotocol/graph-cli@${version}: ${String(error).split("\n").slice(0, 3).join(" ")}`);
+      return null;
+    }
+  }
+  return existsSync(path.join(packageDir, "package.json")) ? packageDir : null;
+}