@ic-reactor/codegen 0.11.1 → 0.12.1

package/README.md

@@ -54,16 +54,16 @@ need to skip `index.generated.ts` and `index.ts`.
 
 You can also use individual generators if you need more granular control:
 
-- **`generateDeclarations`**: Generates `.js` (factory), `.d.ts` (types), and `.did` copy.
-- **`generateReactorFile`**: Generates the managed `index.generated.ts` implementation using either `DisplayReactor` or `Reactor`.
+- **`generateDeclarations`**: Writes `declarations/<did-basename>.js` (factory), `.d.ts` (types), and a `.did` copy. The `declarations/` directory is wiped and recreated on every run.
+- **`generateReactorFile`**: Generates the managed `index.generated.ts` implementation using any `ReactorClassName` — `Reactor`, `DisplayReactor` (default), `CandidReactor`, `CandidDisplayReactor`, or `MetadataDisplayReactor`. With `target: "react"` it also emits the six `createActorHooks` exports (`use<Canister>Query`, `use<Canister>SuspenseQuery`, `use<Canister>InfiniteQuery`, `use<Canister>SuspenseInfiniteQuery`, `use<Canister>Mutation`, `use<Canister>Method`). No `createQuery` / `createMutation` objects are generated.
 - **`generateReactorEntryFile`**: Generates the stable `index.ts` wrapper that re-exports from `index.generated.ts`.
 - **`generateClientFile`**: Generates a `ClientManager` boilerplate file that
   imports `ClientManager` from `@ic-reactor/react`.
 
 ## Utilities
 
-- **`parseDIDFile`**: Parses a `.did` file and extracts method signatures.
-- **`toPascalCase` / `toCamelCase`**: Naming helpers.
+- **`parseDIDFile` / `extractMethods`**: Parse a `.did` file and extract method signatures.
+- **`toPascalCase` / `getReactorName` / `getServiceTypeName`**: Naming helpers.
 
 ## License
 

package/dist/index.cjs

@@ -30,6 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CANISTER_NAME_PATTERN: () => CANISTER_NAME_PATTERN,
+  CODEGEN_TARGETS: () => CODEGEN_TARGETS,
+  CodegenConfigError: () => CodegenConfigError,
+  REACTOR_CLASS_NAMES: () => REACTOR_CLASS_NAMES,
+  assertContainedPath: () => assertContainedPath,
+  assertOneOf: () => assertOneOf,
+  assertSafeCanisterConfig: () => assertSafeCanisterConfig,
+  assertSafeCanisterName: () => assertSafeCanisterName,
+  assertSafeModuleSpecifier: () => assertSafeModuleSpecifier,
   declarationsExist: () => declarationsExist,
   extractMethods: () => extractMethods,
   generateClientFile: () => generateClientFile,
@@ -39,14 +48,15 @@ __export(index_exports, {
   getReactorName: () => getReactorName,
   getServiceTypeName: () => getServiceTypeName,
   parseDIDFile: () => parseDIDFile,
+  resolveContainedOutDir: () => resolveContainedOutDir,
   runCanisterPipeline: () => runCanisterPipeline,
   toPascalCase: () => toPascalCase
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/pipeline.ts
-var import_node_fs2 = __toESM(require("fs"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 
 // src/generators/declarations.ts
 var import_parser = require("@ic-reactor/parser");
@@ -122,6 +132,9 @@ function getReactorName(canisterName) {
 function getServiceTypeName(canisterName) {
   return `${toPascalCase(canisterName)}Service`;
 }
+function getHookPrefix(canisterName) {
+  return toPascalCase(canisterName);
+}
 
 // src/generators/reactor.ts
 function getReactorClassImportSource(reactorClass, runtimeTarget) {
@@ -133,6 +146,10 @@ function getReactorClassImportSource(reactorClass, runtimeTarget) {
     case "CandidDisplayReactor":
     case "MetadataDisplayReactor":
       return "@ic-reactor/candid";
+    default:
+      throw new Error(
+        `Unknown reactor class ${JSON.stringify(reactorClass)}. Expected one of: Reactor, DisplayReactor, CandidReactor, CandidDisplayReactor, MetadataDisplayReactor.`
+      );
   }
 }
 function generateReactorFile(options) {
@@ -166,9 +183,9 @@ export const {
   useActorMethod: use${pascalName}Method,
 } = createActorHooks(${reactorName})
 ` : "";
-  return `${runtimeTarget === "react" ? 'import { createActorHooks } from "@ic-reactor/react"\n' : ""}import { ${reactorClass} } from "${reactorImportSource}"
-import { clientManager } from "${clientManagerPath}"
-import { idlFactory, type _SERVICE } from "${declarationsPath}"
+  return `${runtimeTarget === "react" ? 'import { createActorHooks } from "@ic-reactor/react"\n' : ""}import { ${reactorClass} } from ${JSON.stringify(reactorImportSource)}
+import { clientManager } from ${JSON.stringify(clientManagerPath)}
+import { idlFactory, type _SERVICE } from ${JSON.stringify(declarationsPath)}
 
 export type ${serviceName} = _SERVICE
 
@@ -177,11 +194,14 @@ export type ${serviceName} = _SERVICE
  *
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
  * This file is overwritten whenever generation runs.
+ *
+ * Keep app-specific logic in the stable \`index.ts\` wrapper (or adjacent
+ * factory modules). Avoid editing this managed file directly.
  */
 export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-${canisterIdLine}  name: "${canisterName}",
+${canisterIdLine}  name: ${JSON.stringify(canisterName)},
 })${hookExports || "\n"}`;
 }
 function generateReactorEntryFile() {
@@ -190,11 +210,176 @@ function generateReactorEntryFile() {
  *
  * Created once by @ic-reactor/codegen and safe to customize.
  * Keep the re-export below if you want generated exports and types to stay in sync.
+ *
+ * Recommended customization points:
+ * - define reusable query/mutation factories
+ * - add app-specific hooks and cache invalidation wiring
+ * - compose generated APIs into route loaders/actions
+ *
+ * Do not edit \`index.generated.ts\`; it is regenerated on each codegen run.
+ * AI guide: https://ic-reactor.b3pay.net/llms-full.txt
+ * Skill install: npx skills add B3Pay/ic-reactor-skills --full-depth --skill ic-reactor-hooks
  */
 export * from "./index.generated"
 `;
 }
 
+// src/validate.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var CodegenConfigError = class extends Error {
+  name = "CodegenConfigError";
+  constructor(message) {
+    super(message);
+  }
+};
+var CANISTER_NAME_PATTERN = /^[A-Za-z0-9_.-]+$/;
+var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var MAX_CANISTER_NAME_LENGTH = 64;
+var HAS_URI_SCHEME = /^(?:[A-Za-z][A-Za-z0-9+.-]*:|\/\/)/;
+var BREAKS_OUT_OF_LITERAL = /["'`\\\u0000-\u001f\u2028\u2029]/;
+function assertSafeCanisterName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new CodegenConfigError(
+      `Invalid canister name: expected a non-empty string, received ${name === void 0 ? "undefined" : JSON.stringify(name)}. Check the "canisters" entries in your ic-reactor.json (or the plugin's "canisters" option).`
+    );
+  }
+  if (name.length > MAX_CANISTER_NAME_LENGTH) {
+    throw new CodegenConfigError(
+      `Invalid canister name ${JSON.stringify(name)}: must be at most ${MAX_CANISTER_NAME_LENGTH} characters.`
+    );
+  }
+  if (!CANISTER_NAME_PATTERN.test(name)) {
+    throw new CodegenConfigError(
+      `Invalid canister name ${JSON.stringify(name)}: may contain only letters, digits, "_", "." and "-" (${CANISTER_NAME_PATTERN.source}). Canister names become directory names, so path separators, quotes and whitespace are not allowed.`
+    );
+  }
+  if (name === "." || name === "..") {
+    throw new CodegenConfigError(
+      `Invalid canister name ${JSON.stringify(name)}: refers to a directory, not a canister.`
+    );
+  }
+  if (toPascalCase(name).length === 0) {
+    throw new CodegenConfigError(
+      `Invalid canister name ${JSON.stringify(name)}: contains no letters or digits, so it collapses to an empty identifier in generated code.`
+    );
+  }
+  const derived = [
+    ["reactor constant", getReactorName(name)],
+    ["service type", getServiceTypeName(name)],
+    ["hook name", `use${getHookPrefix(name)}Query`]
+  ];
+  for (const [what, identifier] of derived) {
+    if (!IDENTIFIER_PATTERN.test(identifier)) {
+      throw new CodegenConfigError(
+        `Invalid canister name ${JSON.stringify(name)}: it derives the ${what} ${JSON.stringify(identifier)}, which is not a valid TypeScript identifier. Rename the canister so it does not begin with a digit.`
+      );
+    }
+  }
+}
+function assertSafeModuleSpecifier(label, specifier) {
+  if (typeof specifier !== "string" || specifier.length === 0) {
+    throw new CodegenConfigError(
+      `Invalid ${label}: expected a non-empty string, received ${specifier === void 0 ? "undefined" : JSON.stringify(specifier)}.`
+    );
+  }
+  if (BREAKS_OUT_OF_LITERAL.test(specifier)) {
+    throw new CodegenConfigError(
+      `Invalid ${label} ${JSON.stringify(specifier)}: must not contain quotes, backslashes or control characters.`
+    );
+  }
+  if (/^\s|\s$/.test(specifier)) {
+    throw new CodegenConfigError(
+      `Invalid ${label} ${JSON.stringify(specifier)}: must not begin or end with whitespace.`
+    );
+  }
+  if (HAS_URI_SCHEME.test(specifier.trim())) {
+    throw new CodegenConfigError(
+      `Invalid ${label} ${JSON.stringify(specifier)}: must be a relative path ("./\u2026", "../\u2026") or a bare package name. URLs are not allowed \u2014 the generated file imports from this specifier.`
+    );
+  }
+}
+var REACTOR_CLASS_NAMES = [
+  "Reactor",
+  "DisplayReactor",
+  "CandidReactor",
+  "CandidDisplayReactor",
+  "MetadataDisplayReactor"
+];
+var CODEGEN_TARGETS = ["react", "core"];
+function assertOneOf(label, value, allowed) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new CodegenConfigError(
+      `Invalid ${label} ${JSON.stringify(value)}: must be one of ${allowed.map((a) => JSON.stringify(a)).join(", ")}.`
+    );
+  }
+}
+function realpathAllowingMissing(target) {
+  let current = import_node_path3.default.resolve(target);
+  const missing = [];
+  for (; ; ) {
+    try {
+      return import_node_path3.default.join(import_node_fs2.default.realpathSync(current), ...missing);
+    } catch {
+      const parent = import_node_path3.default.dirname(current);
+      if (parent === current) return import_node_path3.default.resolve(target);
+      missing.unshift(import_node_path3.default.basename(current));
+      current = parent;
+    }
+  }
+}
+function assertContainedPath(label, resolved, projectRoot, original = resolved) {
+  const relative = import_node_path3.default.relative(
+    realpathAllowingMissing(projectRoot),
+    realpathAllowingMissing(resolved)
+  );
+  const [firstSegment] = relative.split(/[\\/]/);
+  if (firstSegment === ".." || import_node_path3.default.isAbsolute(relative)) {
+    throw new CodegenConfigError(
+      `Invalid ${label} ${JSON.stringify(original)}: resolves to ${JSON.stringify(resolved)}, which is outside the project root ${JSON.stringify(import_node_path3.default.resolve(projectRoot))}. Generated output must stay inside the project \u2014 generated directories are deleted and rewritten on every run.`
+    );
+  }
+}
+function resolveContainedOutDir(label, outDir, projectRoot) {
+  if (typeof outDir !== "string" || outDir.length === 0) {
+    throw new CodegenConfigError(
+      `Invalid ${label}: expected a non-empty string, received ${outDir === void 0 ? "undefined" : JSON.stringify(outDir)}.`
+    );
+  }
+  const resolved = import_node_path3.default.isAbsolute(outDir) ? import_node_path3.default.resolve(outDir) : import_node_path3.default.resolve(projectRoot, outDir);
+  assertContainedPath(label, resolved, projectRoot, outDir);
+  return resolved;
+}
+function assertSafeCanisterConfig(options) {
+  const {
+    name,
+    canisterOutDir,
+    globalOutDir,
+    clientManagerPath,
+    projectRoot,
+    mode,
+    target
+  } = options;
+  assertSafeCanisterName(name);
+  assertSafeModuleSpecifier("clientManagerPath", clientManagerPath);
+  if (mode != null) assertOneOf("mode", mode, REACTOR_CLASS_NAMES);
+  if (target != null) assertOneOf("target", target, CODEGEN_TARGETS);
+  const outDir = canisterOutDir != null ? resolveContainedOutDir(
+    `outDir for canister ${JSON.stringify(name)}`,
+    canisterOutDir,
+    projectRoot
+  ) : import_node_path3.default.join(
+    resolveContainedOutDir("outDir", globalOutDir, projectRoot),
+    name
+  );
+  assertContainedPath(
+    `output directory for canister ${JSON.stringify(name)}`,
+    outDir,
+    projectRoot
+  );
+  return { name, outDir, clientManagerPath };
+}
+
 // src/pipeline.ts
 function resolveReactorClass(canisterConfig) {
   return canisterConfig.mode ?? "DisplayReactor";
@@ -220,8 +405,30 @@ async function runCanisterPipeline(options) {
   } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
   const files = [];
-  const resolvedDidFile = import_node_path3.default.isAbsolute(didFile) ? didFile : import_node_path3.default.resolve(projectRoot, didFile);
-  if (!import_node_fs2.default.existsSync(resolvedDidFile)) {
+  let validated;
+  try {
+    validated = assertSafeCanisterConfig({
+      name,
+      canisterOutDir: canisterConfig.outDir,
+      globalOutDir: globalConfig.outDir,
+      clientManagerPath: clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients",
+      projectRoot,
+      mode: canisterConfig.mode,
+      target: canisterConfig.target ?? globalConfig.target
+    });
+  } catch (err) {
+    if (err instanceof CodegenConfigError) {
+      return {
+        canisterName: typeof name === "string" ? name : String(name),
+        success: false,
+        files,
+        error: err.message
+      };
+    }
+    throw err;
+  }
+  const resolvedDidFile = import_node_path4.default.isAbsolute(didFile) ? didFile : import_node_path4.default.resolve(projectRoot, didFile);
+  if (!import_node_fs3.default.existsSync(resolvedDidFile)) {
     return {
       canisterName: name,
       success: false,
@@ -229,8 +436,8 @@ async function runCanisterPipeline(options) {
       error: `DID file not found: ${resolvedDidFile}`
     };
   }
-  const canisterOutDir = canisterConfig.outDir != null ? import_node_path3.default.isAbsolute(canisterConfig.outDir) ? canisterConfig.outDir : import_node_path3.default.resolve(projectRoot, canisterConfig.outDir) : import_node_path3.default.resolve(projectRoot, globalConfig.outDir, name);
-  const resolvedClientManagerPath = clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients";
+  const canisterOutDir = validated.outDir;
+  const resolvedClientManagerPath = validated.clientManagerPath;
   try {
     const declResult = await generateDeclarations({
       didFile: resolvedDidFile,
@@ -261,8 +468,8 @@ async function runCanisterPipeline(options) {
       files
     };
   }
-  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.generated.ts");
-  const entryPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  const reactorPath = import_node_path4.default.join(canisterOutDir, "index.generated.ts");
+  const entryPath = import_node_path4.default.join(canisterOutDir, "index.ts");
   const reactorClass = resolveReactorClass(canisterConfig);
   const runtimeTarget = resolveRuntimeTarget(canisterConfig, globalConfig);
   try {
@@ -275,16 +482,16 @@ async function runCanisterPipeline(options) {
       reactorClass
     });
     const entryContent = generateReactorEntryFile();
-    import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
-    import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+    import_node_fs3.default.mkdirSync(canisterOutDir, { recursive: true });
+    import_node_fs3.default.writeFileSync(reactorPath, reactorContent);
     files.push({ success: true, filePath: reactorPath });
-    if (!import_node_fs2.default.existsSync(entryPath)) {
-      import_node_fs2.default.writeFileSync(entryPath, entryContent);
+    if (!import_node_fs3.default.existsSync(entryPath)) {
+      import_node_fs3.default.writeFileSync(entryPath, entryContent);
       files.push({ success: true, filePath: entryPath });
     } else {
-      const existingEntryContent = import_node_fs2.default.readFileSync(entryPath, "utf-8");
+      const existingEntryContent = import_node_fs3.default.readFileSync(entryPath, "utf-8");
       if (isLegacyGeneratedIndexFile(existingEntryContent) || isManagedEntryWrapper(existingEntryContent, entryContent)) {
-        import_node_fs2.default.writeFileSync(entryPath, entryContent);
+        import_node_fs3.default.writeFileSync(entryPath, entryContent);
         files.push({ success: true, filePath: entryPath });
       } else {
         files.push({ success: true, filePath: entryPath, skipped: true });
@@ -312,7 +519,7 @@ async function runCanisterPipeline(options) {
 
 // src/parser.ts
 var import_parser2 = require("@ic-reactor/parser");
-var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_fs4 = __toESM(require("fs"), 1);
 function extractMethods(didContent) {
   try {
     const jsContent = (0, import_parser2.didToJs)(didContent);
@@ -337,10 +544,10 @@ function extractMethods(didContent) {
   }
 }
 function parseDIDFile(didFilePath) {
-  if (!import_node_fs3.default.existsSync(didFilePath)) {
+  if (!import_node_fs4.default.existsSync(didFilePath)) {
     throw new Error(`DID file not found: ${didFilePath}`);
   }
-  const content = import_node_fs3.default.readFileSync(didFilePath, "utf-8");
+  const content = import_node_fs4.default.readFileSync(didFilePath, "utf-8");
   return extractMethods(content);
 }
 
@@ -361,12 +568,20 @@ ${queryClientImport}
  */
 export const clientManager = new ClientManager({
   queryClient,
-  withCanisterEnv: true,
 })
 `;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CANISTER_NAME_PATTERN,
+  CODEGEN_TARGETS,
+  CodegenConfigError,
+  REACTOR_CLASS_NAMES,
+  assertContainedPath,
+  assertOneOf,
+  assertSafeCanisterConfig,
+  assertSafeCanisterName,
+  assertSafeModuleSpecifier,
   declarationsExist,
   extractMethods,
   generateClientFile,
@@ -376,6 +591,7 @@ export const clientManager = new ClientManager({
   getReactorName,
   getServiceTypeName,
   parseDIDFile,
+  resolveContainedOutDir,
   runCanisterPipeline,
   toPascalCase
 });

package/dist/index.d.cts

@@ -140,6 +140,116 @@ declare function getReactorName(canisterName: string): string;
  */
 declare function getServiceTypeName(canisterName: string): string;
 
+/**
+ * Config validation for the codegen pipeline.
+ *
+ * Every value validated here arrives from a project's `ic-reactor.json` or from
+ * `@ic-reactor/vite-plugin` options — that is, from a file in a repository the
+ * user may have merely cloned. The pipeline turns those values into filesystem
+ * paths it recursively deletes and into source text it writes into the user's
+ * bundle, so they are treated as untrusted input rather than as configuration.
+ *
+ * Validation lives here, at the pipeline's own entry point, rather than in the
+ * CLI's interactive prompt: the prompt only covers one of the three entry paths
+ * (hand-edited config and plugin options bypass it entirely).
+ */
+
+/**
+ * Thrown when a canister config would produce an unsafe path or unsafe
+ * generated source. Callers convert this into a `PipelineResult` error.
+ */
+declare class CodegenConfigError extends Error {
+    readonly name = "CodegenConfigError";
+    constructor(message: string);
+}
+/**
+ * Characters allowed in a canister name.
+ *
+ * A canister name becomes a directory segment, so this excludes path
+ * separators, quotes, whitespace and control characters. It deliberately does
+ * NOT require a leading letter: `dfx` places no restriction on canister names,
+ * and real projects use `_private` and `my.canister`, both of which derive
+ * perfectly good identifiers. Identifier validity is enforced separately, on
+ * the *derived* names, by {@link assertSafeCanisterName}.
+ */
+declare const CANISTER_NAME_PATTERN: RegExp;
+/**
+ * Assert that a canister name is safe to use as a path segment and as the stem
+ * of a generated identifier.
+ *
+ * Rejecting a leading digit here is what stops `2048_game` from reaching the
+ * generator, where it would become `export const 2048GameReactor` — invalid
+ * TypeScript emitted with a success status.
+ */
+declare function assertSafeCanisterName(name: unknown): asserts name is string;
+/**
+ * Assert that a module specifier we interpolate into an `import` statement is a
+ * relative path or a bare package name — never a URL.
+ *
+ * A `https://…` specifier here would make the generated module pull code from a
+ * remote host at import time, inside the user's own bundle.
+ */
+declare function assertSafeModuleSpecifier(label: string, specifier: unknown): asserts specifier is string;
+/** Reactor classes the generator knows how to emit an import for. */
+declare const REACTOR_CLASS_NAMES: readonly ReactorClassName[];
+/** Runtime targets the generator knows how to emit. */
+declare const CODEGEN_TARGETS: readonly CodegenTarget[];
+/**
+ * Assert a config value is one of a closed set.
+ *
+ * `mode` and `target` are interpolated into emitted source as bare identifiers
+ * and module specifiers, so an unrecognized value is not merely unsupported —
+ * it is injected.
+ */
+declare function assertOneOf<T extends string>(label: string, value: unknown, allowed: readonly T[]): asserts value is T;
+/**
+ * Assert that an already-resolved absolute path lies inside `projectRoot`.
+ *
+ * Containment is decided on the real on-disk locations: `path.resolve` does not
+ * follow symlinks, so a purely lexical comparison can be walked out of via a
+ * symlink placed inside the project root.
+ *
+ * @param original - the path as the user wrote it, for the error message
+ */
+declare function assertContainedPath(label: string, resolved: string, projectRoot: string, original?: string): void;
+/**
+ * Resolve `outDir` against `projectRoot` and assert the result stays inside it.
+ *
+ * The pipeline recursively deletes `<outDir>/declarations` before every
+ * generation, so an `outDir` that escapes the project root turns a config file
+ * into an arbitrary-directory delete.
+ */
+declare function resolveContainedOutDir(label: string, outDir: unknown, projectRoot: string): string;
+interface ValidatedCanisterPaths {
+    /** The validated canister name. */
+    name: string;
+    /** Absolute output directory, guaranteed to be inside `projectRoot`. */
+    outDir: string;
+    /** Validated module specifier for the client manager import. */
+    clientManagerPath: string;
+}
+interface ValidateCanisterConfigOptions {
+    name: unknown;
+    /** Per-canister `outDir`, if the config sets one. */
+    canisterOutDir?: unknown;
+    /** Global `outDir`; the canister name is appended to it when used. */
+    globalOutDir: unknown;
+    clientManagerPath: unknown;
+    projectRoot: string;
+    /** Resolved reactor class (`canisterConfig.mode`), if the config sets one. */
+    mode?: unknown;
+    /** Resolved runtime target (`canisterConfig.target` / global `target`). */
+    target?: unknown;
+}
+/**
+ * Validate one canister's config and return the resolved, contained paths the
+ * pipeline should use.
+ *
+ * Call this before any filesystem work: it is the single choke point that all
+ * three entry paths (CLI, vite plugin, direct API) share.
+ */
+declare function assertSafeCanisterConfig(options: ValidateCanisterConfigOptions): ValidatedCanisterPaths;
+
 /**
  * Candid Parser Utilities
  *
@@ -283,4 +393,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { CANISTER_NAME_PATTERN, CODEGEN_TARGETS, type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, CodegenConfigError, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, REACTOR_CLASS_NAMES, type ReactorClassName, type ReactorGeneratorOptions, type ValidateCanisterConfigOptions, type ValidatedCanisterPaths, assertContainedPath, assertOneOf, assertSafeCanisterConfig, assertSafeCanisterName, assertSafeModuleSpecifier, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, resolveContainedOutDir, runCanisterPipeline, toPascalCase };

package/dist/index.d.ts

@@ -140,6 +140,116 @@ declare function getReactorName(canisterName: string): string;
  */
 declare function getServiceTypeName(canisterName: string): string;
 
+/**
+ * Config validation for the codegen pipeline.
+ *
+ * Every value validated here arrives from a project's `ic-reactor.json` or from
+ * `@ic-reactor/vite-plugin` options — that is, from a file in a repository the
+ * user may have merely cloned. The pipeline turns those values into filesystem
+ * paths it recursively deletes and into source text it writes into the user's
+ * bundle, so they are treated as untrusted input rather than as configuration.
+ *
+ * Validation lives here, at the pipeline's own entry point, rather than in the
+ * CLI's interactive prompt: the prompt only covers one of the three entry paths
+ * (hand-edited config and plugin options bypass it entirely).
+ */
+
+/**
+ * Thrown when a canister config would produce an unsafe path or unsafe
+ * generated source. Callers convert this into a `PipelineResult` error.
+ */
+declare class CodegenConfigError extends Error {
+    readonly name = "CodegenConfigError";
+    constructor(message: string);
+}
+/**
+ * Characters allowed in a canister name.
+ *
+ * A canister name becomes a directory segment, so this excludes path
+ * separators, quotes, whitespace and control characters. It deliberately does
+ * NOT require a leading letter: `dfx` places no restriction on canister names,
+ * and real projects use `_private` and `my.canister`, both of which derive
+ * perfectly good identifiers. Identifier validity is enforced separately, on
+ * the *derived* names, by {@link assertSafeCanisterName}.
+ */
+declare const CANISTER_NAME_PATTERN: RegExp;
+/**
+ * Assert that a canister name is safe to use as a path segment and as the stem
+ * of a generated identifier.
+ *
+ * Rejecting a leading digit here is what stops `2048_game` from reaching the
+ * generator, where it would become `export const 2048GameReactor` — invalid
+ * TypeScript emitted with a success status.
+ */
+declare function assertSafeCanisterName(name: unknown): asserts name is string;
+/**
+ * Assert that a module specifier we interpolate into an `import` statement is a
+ * relative path or a bare package name — never a URL.
+ *
+ * A `https://…` specifier here would make the generated module pull code from a
+ * remote host at import time, inside the user's own bundle.
+ */
+declare function assertSafeModuleSpecifier(label: string, specifier: unknown): asserts specifier is string;
+/** Reactor classes the generator knows how to emit an import for. */
+declare const REACTOR_CLASS_NAMES: readonly ReactorClassName[];
+/** Runtime targets the generator knows how to emit. */
+declare const CODEGEN_TARGETS: readonly CodegenTarget[];
+/**
+ * Assert a config value is one of a closed set.
+ *
+ * `mode` and `target` are interpolated into emitted source as bare identifiers
+ * and module specifiers, so an unrecognized value is not merely unsupported —
+ * it is injected.
+ */
+declare function assertOneOf<T extends string>(label: string, value: unknown, allowed: readonly T[]): asserts value is T;
+/**
+ * Assert that an already-resolved absolute path lies inside `projectRoot`.
+ *
+ * Containment is decided on the real on-disk locations: `path.resolve` does not
+ * follow symlinks, so a purely lexical comparison can be walked out of via a
+ * symlink placed inside the project root.
+ *
+ * @param original - the path as the user wrote it, for the error message
+ */
+declare function assertContainedPath(label: string, resolved: string, projectRoot: string, original?: string): void;
+/**
+ * Resolve `outDir` against `projectRoot` and assert the result stays inside it.
+ *
+ * The pipeline recursively deletes `<outDir>/declarations` before every
+ * generation, so an `outDir` that escapes the project root turns a config file
+ * into an arbitrary-directory delete.
+ */
+declare function resolveContainedOutDir(label: string, outDir: unknown, projectRoot: string): string;
+interface ValidatedCanisterPaths {
+    /** The validated canister name. */
+    name: string;
+    /** Absolute output directory, guaranteed to be inside `projectRoot`. */
+    outDir: string;
+    /** Validated module specifier for the client manager import. */
+    clientManagerPath: string;
+}
+interface ValidateCanisterConfigOptions {
+    name: unknown;
+    /** Per-canister `outDir`, if the config sets one. */
+    canisterOutDir?: unknown;
+    /** Global `outDir`; the canister name is appended to it when used. */
+    globalOutDir: unknown;
+    clientManagerPath: unknown;
+    projectRoot: string;
+    /** Resolved reactor class (`canisterConfig.mode`), if the config sets one. */
+    mode?: unknown;
+    /** Resolved runtime target (`canisterConfig.target` / global `target`). */
+    target?: unknown;
+}
+/**
+ * Validate one canister's config and return the resolved, contained paths the
+ * pipeline should use.
+ *
+ * Call this before any filesystem work: it is the single choke point that all
+ * three entry paths (CLI, vite plugin, direct API) share.
+ */
+declare function assertSafeCanisterConfig(options: ValidateCanisterConfigOptions): ValidatedCanisterPaths;
+
 /**
  * Candid Parser Utilities
  *
@@ -283,4 +393,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { CANISTER_NAME_PATTERN, CODEGEN_TARGETS, type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, CodegenConfigError, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, REACTOR_CLASS_NAMES, type ReactorClassName, type ReactorGeneratorOptions, type ValidateCanisterConfigOptions, type ValidatedCanisterPaths, assertContainedPath, assertOneOf, assertSafeCanisterConfig, assertSafeCanisterName, assertSafeModuleSpecifier, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, resolveContainedOutDir, runCanisterPipeline, toPascalCase };