@ic-reactor/cli 0.4.1 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # @ic-reactor/cli
 
-> 🔧 Command-line tool for generating IC reactor hooks and declarations.
+> 🔧 Command-line tool for generating type-safe React hooks for ICP canisters.
 
-The `@ic-reactor/cli` helps you generate TypeScript declarations and React hooks from your Candid files. It provides a simple way to keep your frontend types and interactions in sync with your backend canisters.
+The `@ic-reactor/cli` helps you generate TypeScript declarations and React hooks from your Candid files. It uses the shared `@ic-reactor/codegen` pipeline to ensure consistency with the Vite plugin.
 
 ## Installation
 
@@ -15,10 +15,10 @@ pnpm add -D @ic-reactor/cli
 ### 1. Initialize your project
 
 ```bash
-npx @ic-reactor/cli init
+npx ic-reactor init
 ```
 
-This creates an `ic-reactor.json` configuration file in your project root.
+This creates an `ic-reactor.json` configuration file in your project root and optionally sets up a default `ClientManager` at `src/clients.ts`.
 
 ### 2. Configure your canisters
 
@@ -26,35 +26,36 @@ Update `ic-reactor.json` with the paths to your Candid files:
 
 ```json
 {
-  "outDir": "./src/canisters",
+  "outDir": "src/declarations",
+  "clientManagerPath": "../../clients",
   "canisters": {
     "backend": {
-      "didFile": "src/declarations/backend.did"
+      "didFile": "src/backend/backend.did"
     }
   }
 }
 ```
 
-### 3. Sync hooks and declarations
+### 3. Generate hooks
 
 ```bash
-npx @ic-reactor/cli sync
+npx ic-reactor generate
 ```
 
 This command will:
 
-1. Regenerate TypeScript declarations for your canisters.
-2. Create an `index.ts` file for each canister with fully typed hooks.
+1. Generate TypeScript declarations (`.d.ts`, `.js`, `.did`) for each canister.
+2. Create an `index.ts` reactor file for each canister with fully typed hooks.
 
 ### 4. Use the generated hooks
 
 Import the hooks directly from the generated output folder:
 
 ```tsx
-import { useActorQuery } from "./canisters/backend"
+import { useBackendQuery } from "./declarations/backend"
 
 function MyComponent() {
-  const { data, isPending } = useActorQuery({
+  const { data, isPending } = useBackendQuery({
     functionName: "get_message",
   })
 
@@ -69,50 +70,52 @@ function MyComponent() {
 Initialize the configuration file (`ic-reactor.json`).
 
 ```bash
-npx @ic-reactor/cli init [options]
+npx ic-reactor init [options]
 
 Options:
   -y, --yes              Skip prompts and use defaults
   -o, --out-dir <path>   Output directory for generated hooks
 ```
 
-### `sync`
+### `generate` (alias: `g`)
 
-Regenerate hooks and declarations based on your configuration and DID files.
+Generate hooks and declarations based on your configuration and DID files.
 
 ```bash
-npx @ic-reactor/cli sync [options]
+npx ic-reactor generate [options]
 
 Options:
-  -c, --canister <name>   Sync only a specific canister
-```
-
-### `list`
-
-List all available methods from a canister's Candid definition.
-
-```bash
-npx @ic-reactor/cli list -c <canister_name>
+  -c, --canister <name>   Generate only for a specific canister
+  --clean                 Clean output directory before generating
 ```
 
 ## Configuration
 
-The `ic-reactor.json` file supports the following options:
+The `ic-reactor.json` file schema:
 
-| Option              | Type                             | Description                                |
-| :------------------ | :------------------------------- | :----------------------------------------- |
-| `outDir`            | `string`                         | Base output directory for generated files. |
-| `canisters`         | `Record<string, CanisterConfig>` | Map of canister names to configurations.   |
-| `clientManagerPath` | `string`                         | Path to a custom `ClientManager` instance. |
-
-### Canister Config
+```typescript
+interface CodegenConfig {
+  /** Default output directory (relative to project root) */
+  outDir: string
+  /** Default import path for the client manager */
+  clientManagerPath?: string
+  /** Canister configurations */
+  canisters: Record<string, CanisterConfig>
+}
 
-| Option              | Type      | Description                                         |
-| :------------------ | :-------- | :-------------------------------------------------- |
-| `didFile`           | `string`  | Path to the `.did` file.                            |
-| `outDir`            | `string`  | Override output directory for this canister.        |
-| `useDisplayReactor` | `boolean` | Use `DisplayReactor` instead of standard `Reactor`. |
-| `clientManagerPath` | `string`  | Override client manager path.                       |
+interface CanisterConfig {
+  /** Canister name (required) */
+  name: string
+  /** Path to the .did file (required) */
+  didFile: string
+  /** Override output directory for this canister */
+  outDir?: string
+  /** Override client manager import path */
+  clientManagerPath?: string
+  /** Optional fixed canister ID */
+  canisterId?: string
+}
+```
 
 ## Requirements
 

package/dist/index.js

@@ -15,9 +15,8 @@ import path from "path";
 var CONFIG_FILE_NAME = "ic-reactor.json";
 var DEFAULT_CONFIG = {
   $schema: "https://raw.githubusercontent.com/B3Pay/ic-reactor/main/packages/cli/schema.json",
-  outDir: "src/lib/canisters",
-  canisters: {},
-  generatedHooks: {}
+  outDir: "src/declarations",
+  canisters: {}
 };
 function findConfigFile(startDir = process.cwd()) {
   let currentDir = startDir;
@@ -59,6 +58,7 @@ function ensureDir(dirPath) {
 }
 
 // src/commands/init.ts
+import { generateClientFile } from "@ic-reactor/codegen";
 async function initCommand(options) {
   console.log();
   p.intro(pc.cyan("\u{1F527} ic-reactor CLI Setup"));
@@ -82,174 +82,95 @@ async function initCommand(options) {
     }
   } else {
     const outDir = await p.text({
-      message: "Where should generated hooks be placed?",
-      placeholder: "src/lib/canisters",
-      defaultValue: "src/lib/canisters",
-      validate: (value) => {
-        if (!value) return "Output directory is required";
-        return void 0;
-      }
+      message: "Where should generated files be placed?",
+      placeholder: "src/declarations",
+      defaultValue: "src/declarations"
     });
-    if (p.isCancel(outDir)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    const addCanister = await p.confirm({
-      message: "Would you like to add a canister now?",
-      initialValue: true
+    if (p.isCancel(outDir)) process.exit(0);
+    const clientManagerPath = await p.text({
+      message: "Relative path for the client manager import?",
+      placeholder: "../../clients",
+      defaultValue: "../../clients"
     });
-    if (p.isCancel(addCanister)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
+    if (p.isCancel(clientManagerPath)) process.exit(0);
     config = {
       ...DEFAULT_CONFIG,
-      outDir
+      outDir,
+      clientManagerPath
     };
+    const addCanister = await p.confirm({
+      message: "Would you like to configure a canister now?",
+      initialValue: true
+    });
+    if (p.isCancel(addCanister)) process.exit(0);
     if (addCanister) {
-      const canisterInfo = await promptForCanister(projectRoot);
-      if (canisterInfo) {
-        config.canisters[canisterInfo.name] = canisterInfo.config;
+      const canister = await promptForCanister(projectRoot);
+      if (canister) {
+        config.canisters[canister.name] = canister;
       }
     }
   }
   const configPath = path2.join(projectRoot, CONFIG_FILE_NAME);
   saveConfig(config, configPath);
-  const fullOutDir = path2.join(projectRoot, config.outDir);
-  ensureDir(fullOutDir);
-  const clientManagerPath = path2.join(projectRoot, "src/lib/clients.ts");
-  if (!fs2.existsSync(clientManagerPath)) {
-    const createClient = await p.confirm({
-      message: "Create a sample client manager at src/lib/clients.ts?",
+  ensureDir(path2.join(projectRoot, config.outDir));
+  const clientManagerFile = path2.join(projectRoot, "src/clients.ts");
+  if (!fs2.existsSync(clientManagerFile)) {
+    const createHelpers = await p.confirm({
+      message: `Create a default client manager at ${pc.green("src/clients.ts")}?`,
       initialValue: true
     });
-    if (!p.isCancel(createClient) && createClient) {
-      ensureDir(path2.dirname(clientManagerPath));
-      fs2.writeFileSync(clientManagerPath, getClientManagerTemplate());
-      p.log.success(`Created ${pc.green("src/lib/clients.ts")}`);
+    if (createHelpers === true) {
+      ensureDir(path2.dirname(clientManagerFile));
+      fs2.writeFileSync(clientManagerFile, generateClientFile());
+      p.log.success(`Created ${pc.green("src/clients.ts")}`);
     }
   }
   p.log.success(`Created ${pc.green(CONFIG_FILE_NAME)}`);
-  p.log.success(`Created ${pc.green(config.outDir)} directory`);
   console.log();
   p.note(
-    `Next steps:
-  
-  1. ${pc.cyan("Add a canister:")}
-     ${pc.dim("npx @ic-reactor/cli add")}
-  
-  2. ${pc.cyan("List available methods:")}
-     ${pc.dim("npx @ic-reactor/cli list -c <canister-name>")}
-  
-  3. ${pc.cyan("Add hooks for specific methods:")}
-     ${pc.dim("npx @ic-reactor/cli add -c <canister> -m <method>")}`,
-    "Getting Started"
+    `To generate hooks, run:
+${pc.cyan("npx ic-reactor generate")}`,
+    "Next Steps"
   );
-  p.outro(pc.green("\u2713 ic-reactor initialized successfully!"));
+  p.outro(pc.green("\u2713 Setup complete!"));
 }
 async function promptForCanister(projectRoot) {
   const name = await p.text({
     message: "Canister name",
     placeholder: "backend",
-    validate: (value) => {
-      if (!value) return "Canister name is required";
-      if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(value)) {
-        return "Canister name must start with a letter and contain only letters, numbers, hyphens, and underscores";
-      }
-      return void 0;
+    validate: (val) => {
+      if (!val) return "Name is required";
+      if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(val)) return "Invalid name format";
     }
   });
   if (p.isCancel(name)) return null;
   const didFile = await p.text({
     message: "Path to .did file",
-    placeholder: "./backend.did",
-    validate: (value) => {
-      if (!value) return "DID file path is required";
-      const fullPath = path2.resolve(projectRoot, value);
-      if (!fs2.existsSync(fullPath)) {
-        return `File not found: ${value}`;
-      }
-      return void 0;
+    placeholder: "./src/backend/backend.did",
+    validate: (val) => {
+      if (!val) return "Path is required";
+      const fullPath = path2.resolve(projectRoot, val);
+      if (!fs2.existsSync(fullPath)) return `File not found: ${val}`;
     }
   });
   if (p.isCancel(didFile)) return null;
-  const clientManagerPath = await p.text({
-    message: "Import path to your client manager (relative from generated hooks)",
-    placeholder: "../../clients",
-    defaultValue: "../../clients"
-  });
-  if (p.isCancel(clientManagerPath)) return null;
-  const useDisplayReactor = await p.confirm({
-    message: "Use DisplayReactor? (auto-converts bigint \u2192 string, Principal \u2192 string)",
-    initialValue: true
-  });
-  if (p.isCancel(useDisplayReactor)) return null;
   return {
     name,
-    config: {
-      didFile,
-      clientManagerPath,
-      useDisplayReactor
-    }
+    didFile
   };
 }
-function getClientManagerTemplate() {
-  return `/**
- * IC Client Manager
- *
- * This file configures the IC agent and client manager for your application.
- * Customize the agent options based on your environment.
- */
-
-import { ClientManager } from "@ic-reactor/react"
-
-/**
- * The client manager handles agent lifecycle and authentication.
- *
- * Configuration options:
- * - host: IC network host (defaults to process env or mainnet)
- * - identity: Initial identity (optional, can be set later)
- * - verifyQuerySignatures: Verify query signatures (recommended for production)
- *
- * For local development, the agent will automatically detect local replica.
- */
-export const clientManager = new ClientManager({
-  // Uncomment for explicit host configuration:
-  // host: process.env.DFX_NETWORK === "local"
-  //   ? "http://localhost:4943"
-  //   : "https://icp-api.io",
-})
-`;
-}
 
-// src/commands/sync.ts
+// src/commands/generate.ts
 import * as p2 from "@clack/prompts";
-import fs3 from "fs";
-import path3 from "path";
 import pc2 from "picocolors";
-
-// src/generators/reactor.ts
-import {
-  generateReactorFile as generateReactorFileFromCodegen
-} from "@ic-reactor/codegen";
-function generateReactorFile(options) {
-  const { canisterName, canisterConfig, config } = options;
-  return generateReactorFileFromCodegen({
-    canisterName,
-    canisterConfig,
-    globalClientManagerPath: config.clientManagerPath
-  });
-}
-
-// src/commands/sync.ts
-import { generateDeclarations } from "@ic-reactor/codegen";
-async function syncCommand(options) {
+import { runCanisterPipeline } from "@ic-reactor/codegen";
+async function generateCommand(options) {
   console.log();
-  p2.intro(pc2.cyan("\u{1F504} Sync Canister Hooks"));
+  p2.intro(pc2.cyan("\u{1F504} Generate Hooks"));
   const configPath = findConfigFile();
   if (!configPath) {
     p2.log.error(
-      `No ${pc2.yellow("reactor.config.json")} found. Run ${pc2.cyan("npx @ic-reactor/cli init")} first.`
+      `No ${pc2.yellow("ic-reactor.json")} found. Run ${pc2.cyan("npx ic-reactor init")} first.`
     );
     process.exit(1);
   }
@@ -264,7 +185,7 @@ async function syncCommand(options) {
     p2.log.error("No canisters configured.");
     process.exit(1);
   }
-  let canistersToSync;
+  let canistersToProcess = [];
   if (options.canister) {
     if (!config.canisters[options.canister]) {
       p2.log.error(
@@ -272,176 +193,70 @@ async function syncCommand(options) {
       );
       process.exit(1);
     }
-    canistersToSync = [options.canister];
+    canistersToProcess = [options.canister];
   } else {
-    canistersToSync = canisterNames;
+    canistersToProcess = canisterNames;
   }
   const spinner2 = p2.spinner();
-  spinner2.start("Syncing hooks...");
-  let totalUpdated = 0;
-  const errors = [];
-  for (const canisterName of canistersToSync) {
-    const canisterConfig = config.canisters[canisterName];
-    const canisterOutDir = path3.join(projectRoot, config.outDir, canisterName);
-    const didFilePath = path3.resolve(projectRoot, canisterConfig.didFile);
-    spinner2.message(`Regenerating declarations for ${canisterName}...`);
+  spinner2.start(
+    `Generating hooks for ${canistersToProcess.length} canisters...`
+  );
+  let successCount = 0;
+  let errorCount = 0;
+  const errorMessages = [];
+  for (const name of canistersToProcess) {
+    const canisterConfig = config.canisters[name];
+    spinner2.message(`Processing ${pc2.cyan(name)}...`);
     try {
-      const bindgenResult = await generateDeclarations({
-        didFile: didFilePath,
-        outDir: canisterOutDir,
-        canisterName
-      });
-      if (!bindgenResult.success) {
-        errors.push(`${canisterName}: ${bindgenResult.error}`);
-        p2.log.warn(
-          `Could not regenerate declarations for ${canisterName}: ${bindgenResult.error}`
-        );
-        continue;
-      }
-      const reactorPath = path3.join(canisterOutDir, "index.ts");
-      const reactorContent = generateReactorFile({
-        canisterName,
+      const result = await runCanisterPipeline({
         canisterConfig,
-        config
+        projectRoot,
+        globalConfig: config
       });
-      fs3.writeFileSync(reactorPath, reactorContent);
-      totalUpdated++;
-    } catch (error) {
-      errors.push(`${canisterName}: ${error.message}`);
-      p2.log.error(`Failed to sync ${canisterName}: ${error.message}`);
+      if (result.success) {
+        successCount++;
+      } else {
+        errorCount++;
+        errorMessages.push(`${name}: ${result.error}`);
+      }
+    } catch (err) {
+      errorCount++;
+      errorMessages.push(
+        `${name}: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
-  spinner2.stop("Sync complete!");
-  if (errors.length > 0) {
+  spinner2.stop("Generation complete");
+  if (errorMessages.length > 0) {
     console.log();
     p2.log.error("Errors encountered:");
-    for (const error of errors) {
-      console.log(`  ${pc2.red("\u2022")} ${error}`);
+    for (const msg of errorMessages) {
+      console.log(`  ${pc2.red("\u2022")} ${msg}`);
     }
   }
   console.log();
-  p2.note(`Updated: ${pc2.green(totalUpdated.toString())} canisters`, "Summary");
-  p2.outro(pc2.green("\u2713 Sync complete!"));
+  p2.note(
+    `Success: ${pc2.green(successCount.toString())}
+Failed:  ${pc2.red(errorCount.toString())}`,
+    "Summary"
+  );
+  if (errorCount > 0) {
+    p2.outro(pc2.red("\u2716 Generation failed with errors."));
+    process.exit(1);
+  } else {
+    p2.outro(pc2.green("\u2713 All hooks generated successfully!"));
+  }
 }
 
-// src/commands/list.ts
-import * as p3 from "@clack/prompts";
-import path4 from "path";
+// src/index.ts
 import pc3 from "picocolors";
-import { parseDIDFile } from "@ic-reactor/codegen";
-async function listCommand(options) {
-  console.log();
-  p3.intro(pc3.cyan("\u{1F4CB} List Canister Methods"));
-  const configPath = findConfigFile();
-  if (!configPath) {
-    p3.log.error(
-      `No ${pc3.yellow("reactor.config.json")} found. Run ${pc3.cyan("npx @ic-reactor/cli init")} first.`
-    );
-    process.exit(1);
-  }
-  const config = loadConfig(configPath);
-  if (!config) {
-    p3.log.error(`Failed to load config from ${pc3.yellow(configPath)}`);
-    process.exit(1);
-  }
-  const projectRoot = getProjectRoot();
-  const canisterNames = Object.keys(config.canisters);
-  if (canisterNames.length === 0) {
-    p3.log.error(
-      `No canisters configured. Add a canister to ${pc3.yellow("reactor.config.json")} first.`
-    );
-    process.exit(1);
-  }
-  let selectedCanister = options.canister;
-  if (!selectedCanister) {
-    if (canisterNames.length === 1) {
-      selectedCanister = canisterNames[0];
-    } else {
-      const result = await p3.select({
-        message: "Select a canister",
-        options: canisterNames.map((name) => ({
-          value: name,
-          label: name
-        }))
-      });
-      if (p3.isCancel(result)) {
-        p3.cancel("Cancelled.");
-        process.exit(0);
-      }
-      selectedCanister = result;
-    }
-  }
-  const canisterConfig = config.canisters[selectedCanister];
-  if (!canisterConfig) {
-    p3.log.error(`Canister ${pc3.yellow(selectedCanister)} not found in config.`);
-    process.exit(1);
-  }
-  const didFilePath = path4.resolve(projectRoot, canisterConfig.didFile);
-  try {
-    const methods = parseDIDFile(didFilePath);
-    if (methods.length === 0) {
-      p3.log.warn(`No methods found in ${pc3.yellow(didFilePath)}`);
-      process.exit(0);
-    }
-    const queries = methods.filter((m) => m.type === "query");
-    const mutations = methods.filter((m) => m.type === "mutation");
-    const generatedMethods = config.generatedHooks[selectedCanister] ?? [];
-    if (queries.length > 0) {
-      console.log();
-      console.log(pc3.bold(pc3.cyan("  Queries:")));
-      for (const method of queries) {
-        const isGenerated = generatedMethods.includes(method.name);
-        const status = isGenerated ? pc3.green("\u2713") : pc3.dim("\u25CB");
-        const argsHint = method.hasArgs ? pc3.dim("(args)") : pc3.dim("()");
-        console.log(`    ${status} ${method.name} ${argsHint}`);
-      }
-    }
-    if (mutations.length > 0) {
-      console.log();
-      console.log(pc3.bold(pc3.yellow("  Mutations (Updates):")));
-      for (const method of mutations) {
-        const isGenerated = generatedMethods.includes(method.name);
-        const status = isGenerated ? pc3.green("\u2713") : pc3.dim("\u25CB");
-        const argsHint = method.hasArgs ? pc3.dim("(args)") : pc3.dim("()");
-        console.log(`    ${status} ${method.name} ${argsHint}`);
-      }
-    }
-    console.log();
-    const generatedCount = generatedMethods.length;
-    const totalCount = methods.length;
-    p3.note(
-      `Total: ${pc3.bold(totalCount.toString())} methods
-Generated: ${pc3.green(generatedCount.toString())} / ${totalCount}
 
-${pc3.green("\u2713")} = hook generated
-${pc3.dim("\u25CB")} = not yet generated`,
-      selectedCanister
-    );
-    if (generatedCount < totalCount) {
-      console.log();
-      console.log(
-        pc3.dim(
-          `  Run ${pc3.cyan(`npx @ic-reactor/cli add -c ${selectedCanister}`)} to add hooks`
-        )
-      );
-    }
-  } catch (error) {
-    p3.log.error(
-      `Failed to parse DID file: ${pc3.yellow(didFilePath)}
-${error.message}`
-    );
-    process.exit(1);
-  }
-  console.log();
-}
+// package.json
+var version = "0.5.0";
 
 // src/index.ts
-import pc4 from "picocolors";
 var program = new Command();
-program.name("ic-reactor").description(
-  pc4.cyan("\u{1F527} Generate shadcn-style React hooks for ICP canisters")
-).version("3.0.0");
-program.command("init").description("Initialize ic-reactor configuration in your project").option("-y, --yes", "Skip prompts and use defaults").option("-o, --out-dir <path>", "Output directory for generated hooks").action(initCommand);
-program.command("sync").description("Sync hooks with .did file changes").option("-c, --canister <name>", "Canister to sync").action(syncCommand);
-program.command("list").description("List available methods from a canister").option("-c, --canister <name>", "Canister to list methods from").action(listCommand);
+program.name("ic-reactor").description(pc3.cyan("\u{1F527} Generate type-safe React hooks for ICP canisters")).version(version);
+program.command("init").description("Initialize ic-reactor configuration in your project").option("-y, --yes", "Skip prompts and use defaults").option("-o, --out-dir <path>", "Output directory for generated files").action(initCommand);
+program.command("generate").alias("g").description("Generate hooks from .did files").option("-c, --canister <name>", "Generate for a specific canister only").option("--clean", "Clean output directory before generating").action(generateCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "CLI tool to generate shadcn-style React hooks for ICP canisters",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "@icp-sdk/core": "^5.0.0",
     "commander": "^14.0.3",
     "picocolors": "^1.1.1",
-    "@ic-reactor/codegen": "0.4.1"
+    "@ic-reactor/codegen": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",