@ic-reactor/cli 0.0.0-dev3 → 0.2.0

package/src/commands/init.ts

@@ -0,0 +1,224 @@
+/**
+ * Init command
+ *
+ * Initializes ic-reactor configuration in the project.
+ */
+
+import * as p from "@clack/prompts"
+import fs from "node:fs"
+import path from "node:path"
+import pc from "picocolors"
+import {
+  CONFIG_FILE_NAME,
+  DEFAULT_CONFIG,
+  findConfigFile,
+  saveConfig,
+  getProjectRoot,
+  ensureDir,
+} from "../utils/config.js"
+import type { ReactorConfig, CanisterConfig } from "../types.js"
+
+interface InitOptions {
+  yes?: boolean
+  outDir?: string
+}
+
+export async function initCommand(options: InitOptions) {
+  console.log()
+  p.intro(pc.cyan("🔧 ic-reactor CLI Setup"))
+
+  // Check if config already exists
+  const existingConfig = findConfigFile()
+  if (existingConfig) {
+    const shouldOverwrite = await p.confirm({
+      message: `Config file already exists at ${pc.yellow(existingConfig)}. Overwrite?`,
+      initialValue: false,
+    })
+
+    if (p.isCancel(shouldOverwrite) || !shouldOverwrite) {
+      p.cancel("Setup cancelled.")
+      process.exit(0)
+    }
+  }
+
+  const projectRoot = getProjectRoot()
+  let config: ReactorConfig
+
+  if (options.yes) {
+    // Use defaults
+    config = { ...DEFAULT_CONFIG }
+    if (options.outDir) {
+      config.outDir = options.outDir
+    }
+  } else {
+    // Interactive mode
+    const outDir = await p.text({
+      message: "Where should generated hooks be placed?",
+      placeholder: "src/canisters",
+      defaultValue: "src/canisters",
+      validate: (value) => {
+        if (!value) return "Output directory is required"
+        return undefined
+      },
+    })
+
+    if (p.isCancel(outDir)) {
+      p.cancel("Setup cancelled.")
+      process.exit(0)
+    }
+
+    // Ask if they want to add a canister now
+    const addCanister = await p.confirm({
+      message: "Would you like to add a canister now?",
+      initialValue: true,
+    })
+
+    if (p.isCancel(addCanister)) {
+      p.cancel("Setup cancelled.")
+      process.exit(0)
+    }
+
+    config = {
+      ...DEFAULT_CONFIG,
+      outDir: outDir as string,
+    }
+
+    if (addCanister) {
+      const canisterInfo = await promptForCanister(projectRoot)
+      if (canisterInfo) {
+        config.canisters[canisterInfo.name] = canisterInfo.config
+      }
+    }
+  }
+
+  // Save config file
+  const configPath = path.join(projectRoot, CONFIG_FILE_NAME)
+  saveConfig(config, configPath)
+
+  // Create output directory
+  const fullOutDir = path.join(projectRoot, config.outDir)
+  ensureDir(fullOutDir)
+
+  // Create a sample client manager if it doesn't exist
+  const clientManagerPath = path.join(projectRoot, "src/lib/client.ts")
+  if (!fs.existsSync(clientManagerPath)) {
+    const createClient = await p.confirm({
+      message: "Create a sample client manager at src/lib/client.ts?",
+      initialValue: true,
+    })
+
+    if (!p.isCancel(createClient) && createClient) {
+      ensureDir(path.dirname(clientManagerPath))
+      fs.writeFileSync(clientManagerPath, getClientManagerTemplate())
+      p.log.success(`Created ${pc.green("src/lib/client.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"
+  )
+
+  p.outro(pc.green("✓ ic-reactor initialized successfully!"))
+}
+
+async function promptForCanister(
+  projectRoot: string
+): Promise<{ name: string; config: CanisterConfig } | null> {
+  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 undefined
+    },
+  })
+
+  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 = path.resolve(projectRoot, value)
+      if (!fs.existsSync(fullPath)) {
+        return `File not found: ${value}`
+      }
+      return undefined
+    },
+  })
+
+  if (p.isCancel(didFile)) return null
+
+  const clientManagerPath = await p.text({
+    message:
+      "Import path to your client manager (relative from generated hooks)",
+    placeholder: "../../lib/client",
+    defaultValue: "../../lib/client",
+  })
+
+  if (p.isCancel(clientManagerPath)) return null
+
+  const useDisplayReactor = await p.confirm({
+    message:
+      "Use DisplayReactor? (auto-converts bigint → string, Principal → string)",
+    initialValue: true,
+  })
+
+  if (p.isCancel(useDisplayReactor)) return null
+
+  return {
+    name: name as string,
+    config: {
+      didFile: didFile as string,
+      clientManagerPath: clientManagerPath as string,
+      useDisplayReactor: useDisplayReactor as boolean,
+    },
+  }
+}
+
+function getClientManagerTemplate(): string {
+  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",
+})
+`
+}

package/src/commands/list.ts

@@ -0,0 +1,144 @@
+/**
+ * List command
+ *
+ * List available methods from a canister's DID file.
+ */
+
+import * as p from "@clack/prompts"
+import path from "node:path"
+import pc from "picocolors"
+import { loadConfig, getProjectRoot, findConfigFile } from "../utils/config.js"
+import { parseDIDFile } from "@ic-reactor/codegen"
+
+interface ListOptions {
+  canister?: string
+}
+
+export async function listCommand(options: ListOptions) {
+  console.log()
+  p.intro(pc.cyan("📋 List Canister Methods"))
+
+  // Load config
+  const configPath = findConfigFile()
+  if (!configPath) {
+    p.log.error(
+      `No ${pc.yellow("reactor.config.json")} found. Run ${pc.cyan("npx @ic-reactor/cli init")} first.`
+    )
+    process.exit(1)
+  }
+
+  const config = loadConfig(configPath)
+  if (!config) {
+    p.log.error(`Failed to load config from ${pc.yellow(configPath)}`)
+    process.exit(1)
+  }
+
+  const projectRoot = getProjectRoot()
+  const canisterNames = Object.keys(config.canisters)
+
+  if (canisterNames.length === 0) {
+    p.log.error(
+      `No canisters configured. Add a canister to ${pc.yellow("reactor.config.json")} first.`
+    )
+    process.exit(1)
+  }
+
+  // Select canister
+  let selectedCanister = options.canister
+
+  if (!selectedCanister) {
+    if (canisterNames.length === 1) {
+      selectedCanister = canisterNames[0]
+    } else {
+      const result = await p.select({
+        message: "Select a canister",
+        options: canisterNames.map((name) => ({
+          value: name,
+          label: name,
+        })),
+      })
+
+      if (p.isCancel(result)) {
+        p.cancel("Cancelled.")
+        process.exit(0)
+      }
+
+      selectedCanister = result as string
+    }
+  }
+
+  const canisterConfig = config.canisters[selectedCanister]
+  if (!canisterConfig) {
+    p.log.error(`Canister ${pc.yellow(selectedCanister)} not found in config.`)
+    process.exit(1)
+  }
+
+  // Parse DID file
+  const didFilePath = path.resolve(projectRoot, canisterConfig.didFile)
+
+  try {
+    const methods = parseDIDFile(didFilePath)
+
+    if (methods.length === 0) {
+      p.log.warn(`No methods found in ${pc.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] ?? []
+
+    // Display queries
+    if (queries.length > 0) {
+      console.log()
+      console.log(pc.bold(pc.cyan("  Queries:")))
+      for (const method of queries) {
+        const isGenerated = generatedMethods.includes(method.name)
+        const status = isGenerated ? pc.green("✓") : pc.dim("○")
+        const argsHint = method.hasArgs ? pc.dim("(args)") : pc.dim("()")
+        console.log(`    ${status} ${method.name} ${argsHint}`)
+      }
+    }
+
+    // Display mutations
+    if (mutations.length > 0) {
+      console.log()
+      console.log(pc.bold(pc.yellow("  Mutations (Updates):")))
+      for (const method of mutations) {
+        const isGenerated = generatedMethods.includes(method.name)
+        const status = isGenerated ? pc.green("✓") : pc.dim("○")
+        const argsHint = method.hasArgs ? pc.dim("(args)") : pc.dim("()")
+        console.log(`    ${status} ${method.name} ${argsHint}`)
+      }
+    }
+
+    // Summary
+    console.log()
+    const generatedCount = generatedMethods.length
+    const totalCount = methods.length
+
+    p.note(
+      `Total: ${pc.bold(totalCount.toString())} methods\n` +
+        `Generated: ${pc.green(generatedCount.toString())} / ${totalCount}\n\n` +
+        `${pc.green("✓")} = hook generated\n` +
+        `${pc.dim("○")} = not yet generated`,
+      selectedCanister
+    )
+
+    if (generatedCount < totalCount) {
+      console.log()
+      console.log(
+        pc.dim(
+          `  Run ${pc.cyan(`npx @ic-reactor/cli add -c ${selectedCanister}`)} to add hooks`
+        )
+      )
+    }
+  } catch (error) {
+    p.log.error(
+      `Failed to parse DID file: ${pc.yellow(didFilePath)}\n${(error as Error).message}`
+    )
+    process.exit(1)
+  }
+
+  console.log()
+}

package/src/commands/sync.ts

@@ -0,0 +1,259 @@
+/**
+ * Sync command
+ *
+ * Regenerate hooks when DID files change.
+ */
+
+import * as p from "@clack/prompts"
+import fs from "node:fs"
+import path from "node:path"
+import pc from "picocolors"
+import {
+  loadConfig,
+  getProjectRoot,
+  findConfigFile,
+  ensureDir,
+} from "../utils/config.js"
+import { parseDIDFile } from "@ic-reactor/codegen"
+import {
+  generateReactorFile,
+  generateQueryHook,
+  generateMutationHook,
+} from "../generators/index.js"
+import { getHookFileName } from "@ic-reactor/codegen"
+import { generateDeclarations } from "@ic-reactor/codegen"
+import type { MethodInfo } from "@ic-reactor/codegen"
+
+interface SyncOptions {
+  canister?: string
+}
+
+export async function syncCommand(options: SyncOptions) {
+  console.log()
+  p.intro(pc.cyan("🔄 Sync Canister Hooks"))
+
+  // Load config
+  const configPath = findConfigFile()
+  if (!configPath) {
+    p.log.error(
+      `No ${pc.yellow("reactor.config.json")} found. Run ${pc.cyan("npx @ic-reactor/cli init")} first.`
+    )
+    process.exit(1)
+  }
+
+  const config = loadConfig(configPath)
+  if (!config) {
+    p.log.error(`Failed to load config from ${pc.yellow(configPath)}`)
+    process.exit(1)
+  }
+
+  const projectRoot = getProjectRoot()
+  const canisterNames = Object.keys(config.canisters)
+
+  if (canisterNames.length === 0) {
+    p.log.error("No canisters configured.")
+    process.exit(1)
+  }
+
+  // Select canisters to sync
+  let canistersToSync: string[]
+
+  if (options.canister) {
+    if (!config.canisters[options.canister]) {
+      p.log.error(
+        `Canister ${pc.yellow(options.canister)} not found in config.`
+      )
+      process.exit(1)
+    }
+    canistersToSync = [options.canister]
+  } else {
+    // Sync all canisters with generated hooks
+    canistersToSync = canisterNames.filter(
+      (name) => (config.generatedHooks[name]?.length ?? 0) > 0
+    )
+
+    if (canistersToSync.length === 0) {
+      p.log.warn("No hooks have been generated yet. Run `add` first.")
+      process.exit(0)
+    }
+  }
+
+  const spinner = p.spinner()
+  spinner.start("Syncing hooks...")
+
+  let totalUpdated = 0
+  let totalSkipped = 0
+  const errors: string[] = []
+
+  for (const canisterName of canistersToSync) {
+    const canisterConfig = config.canisters[canisterName]
+    const generatedMethods = config.generatedHooks[canisterName] ?? []
+
+    if (generatedMethods.length === 0) {
+      continue
+    }
+
+    // Parse DID file
+    const didFilePath = path.resolve(projectRoot, canisterConfig.didFile)
+    let methods: MethodInfo[]
+
+    try {
+      methods = parseDIDFile(didFilePath)
+    } catch (error) {
+      errors.push(
+        `${canisterName}: Failed to parse DID file - ${(error as Error).message}`
+      )
+      continue
+    }
+
+    // Normalize hooks to objects
+    const hooks = generatedMethods.map((h) =>
+      typeof h === "string" ? { name: h } : h
+    )
+
+    // Check for removed methods
+    const currentMethodNames = methods.map((m) => m.name)
+    const removedMethods = hooks
+      .filter((h) => !currentMethodNames.includes(h.name))
+      .map((h) => h.name)
+
+    if (removedMethods.length > 0) {
+      p.log.warn(
+        `${canisterName}: Methods removed from DID: ${pc.yellow(removedMethods.join(", "))}`
+      )
+    }
+
+    // Check for new methods
+    const generatedNames = hooks.map((h) => h.name)
+    const newMethods = methods.filter((m) => !generatedNames.includes(m.name))
+
+    if (newMethods.length > 0) {
+      p.log.info(
+        `${canisterName}: New methods available: ${pc.cyan(newMethods.map((m) => m.name).join(", "))}`
+      )
+    }
+
+    // Regenerate declarations if missing
+    const canisterOutDir = path.join(projectRoot, config.outDir, canisterName)
+    const declarationsDir = path.join(canisterOutDir, "declarations")
+
+    // Check if declarations exist and have files (not just nested empty dir)
+    const declarationsExist =
+      fs.existsSync(declarationsDir) &&
+      fs
+        .readdirSync(declarationsDir)
+        .some((f) => f.endsWith(".ts") || f.endsWith(".js"))
+
+    if (!declarationsExist) {
+      spinner.message(`Regenerating declarations for ${canisterName}...`)
+      const bindgenResult = await generateDeclarations({
+        didFile: didFilePath,
+        outDir: canisterOutDir,
+        canisterName,
+      })
+
+      if (bindgenResult.success) {
+        totalUpdated++
+      } else {
+        p.log.warn(
+          `Could not regenerate declarations for ${canisterName}: ${bindgenResult.error}`
+        )
+      }
+    }
+
+    // Regenerate reactor.ts
+    const reactorPath = path.join(canisterOutDir, "reactor.ts")
+
+    const reactorContent = generateReactorFile({
+      canisterName,
+      canisterConfig,
+      config,
+      outDir: canisterOutDir,
+    })
+    fs.writeFileSync(reactorPath, reactorContent)
+    totalUpdated++
+
+    // Regenerate existing hooks
+    const hooksOutDir = path.join(canisterOutDir, "hooks")
+    ensureDir(hooksOutDir)
+
+    for (const hookConfig of hooks) {
+      const methodName = hookConfig.name
+      const method = methods.find((m) => m.name === methodName)
+
+      if (!method) {
+        // Method was removed, skip but warn
+        totalSkipped++
+        continue
+      }
+
+      // Determine hook type
+      let hookType: string = hookConfig.type || (method.type as string)
+
+      // If no explicit type in config, try to infer from existing files (backward compat)
+      if (!hookConfig.type) {
+        const infiniteQueryFileName = getHookFileName(
+          methodName,
+          "infiniteQuery"
+        )
+        if (fs.existsSync(path.join(hooksOutDir, infiniteQueryFileName))) {
+          hookType = "infiniteQuery"
+        }
+      }
+
+      const fileName = getHookFileName(methodName, hookType)
+      let content: string
+
+      if (hookType.includes("Query")) {
+        content = generateQueryHook({
+          canisterName,
+          method,
+          config,
+          type: hookType as any,
+        })
+      } else {
+        content = generateMutationHook({
+          canisterName,
+          method,
+          config,
+        })
+      }
+
+      const filePath = path.join(hooksOutDir, fileName)
+
+      // Check if file exists and has been customized
+      if (fs.existsSync(filePath)) {
+        const existingContent = fs.readFileSync(filePath, "utf-8")
+
+        // If content is different from what we'd generate, skip (user customized)
+        if (existingContent !== content) {
+          totalSkipped++
+          continue
+        }
+      }
+
+      fs.writeFileSync(filePath, content)
+      totalUpdated++
+    }
+  }
+
+  spinner.stop("Sync complete!")
+
+  // Display results
+  if (errors.length > 0) {
+    console.log()
+    p.log.error("Errors encountered:")
+    for (const error of errors) {
+      console.log(`  ${pc.red("•")} ${error}`)
+    }
+  }
+
+  console.log()
+  p.note(
+    `Updated: ${pc.green(totalUpdated.toString())} files\n` +
+      `Skipped: ${pc.dim(totalSkipped.toString())} files (preserved customizations)`,
+    "Summary"
+  )
+
+  p.outro(pc.green("✓ Sync complete!"))
+}

package/src/generators/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Generators barrel export
+ */
+
+export { generateReactorFile } from "./reactor.js"
+export { generateQueryHook } from "./query.js"
+export { generateMutationHook } from "./mutation.js"
+export { generateInfiniteQueryHook } from "./infiniteQuery.js"

package/src/generators/infiniteQuery.ts

@@ -0,0 +1,34 @@
+/**
+ * Infinite Query hook generator
+ *
+ * Generates createInfiniteQuery-based hooks for paginated canister methods.
+ */
+
+import {
+  type MethodInfo,
+  type HookType,
+  generateInfiniteQueryHook as generateInfiniteQueryHookFromCodegen,
+} from "@ic-reactor/codegen"
+import type { ReactorConfig } from "../types.js"
+
+export interface InfiniteQueryHookOptions {
+  canisterName: string
+  method: MethodInfo
+  type?: HookType
+  config: ReactorConfig // Unused
+}
+
+/**
+ * Generate an infinite query hook file content
+ */
+export function generateInfiniteQueryHook(
+  options: InfiniteQueryHookOptions
+): string {
+  const { canisterName, method, type } = options
+
+  return generateInfiniteQueryHookFromCodegen({
+    canisterName,
+    method,
+    type,
+  })
+}

package/src/generators/mutation.ts

@@ -0,0 +1,29 @@
+/**
+ * Mutation hook generator
+ *
+ * Generates createMutation-based hooks for canister update methods.
+ */
+
+import {
+  type MethodInfo,
+  generateMutationHook as generateMutationHookFromCodegen,
+} from "@ic-reactor/codegen"
+import type { ReactorConfig } from "../types.js"
+
+export interface MutationHookOptions {
+  canisterName: string
+  method: MethodInfo
+  config: ReactorConfig // Unused
+}
+
+/**
+ * Generate a mutation hook file content
+ */
+export function generateMutationHook(options: MutationHookOptions): string {
+  const { canisterName, method } = options
+
+  return generateMutationHookFromCodegen({
+    canisterName,
+    method,
+  })
+}