@ic-reactor/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,23 +1,12 @@
 # @ic-reactor/cli
 
-> 🔧 Generate shadcn-style React hooks for ICP canisters
+> 🔧 Command-line tool for generating IC reactor hooks and declarations.
 
-The `@ic-reactor/cli` generates **customizable, user-owned** React hooks for interacting with Internet Computer canisters. Unlike build-time code generation, you get full control over the generated code.
-
-## Philosophy
-
-Like [shadcn/ui](https://ui.shadcn.com/), this CLI generates code **into your project** rather than hiding it in `node_modules`. This means:
-
-- ✅ **Full control** - Customize hooks to your needs
-- ✅ **No magic** - See exactly what's happening
-- ✅ **Version controlled** - Hooks are part of your codebase
-- ✅ **Framework agnostic** - Works with any React setup
+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.
 
 ## Installation
 
 ```bash
-npm install -D @ic-reactor/cli
-# or
 pnpm add -D @ic-reactor/cli
 ```
 
@@ -29,38 +18,47 @@ pnpm add -D @ic-reactor/cli
 npx @ic-reactor/cli init
 ```
 
-This creates:
+This creates an `ic-reactor.json` configuration file in your project root.
 
-- `reactor.config.json` - Configuration file
-- `src/lib/client.ts` - Client manager (optional)
-- `src/canisters/` - Output directory for hooks
+### 2. Configure your canisters
 
-### 2. Add hooks for a canister
+Update `ic-reactor.json` with the paths to your Candid files:
+
+```json
+{
+  "outDir": "./src/canisters",
+  "canisters": {
+    "backend": {
+      "didFile": "src/declarations/backend.did"
+    }
+  }
+}
+```
+
+### 3. Sync hooks and declarations
 
 ```bash
-npx @ic-reactor/cli add
+npx @ic-reactor/cli sync
 ```
 
-Interactive prompts will guide you through:
+This command will:
 
-1. Selecting a canister
-2. Choosing methods to generate hooks for
-3. Selecting hook types (Query, Suspense Query, Infinite Query, Mutation)
+1. Regenerate TypeScript declarations for your canisters.
+2. Create an `index.ts` file for each canister with fully typed hooks.
 
-### 3. Use the hooks
+### 4. Use the generated hooks
+
+Import the hooks directly from the generated output folder:
 
 ```tsx
-import { useGetMessageQuery, getMessageQuery } from "./canisters/backend/hooks"
+import { useActorQuery } from "./canisters/backend"
 
 function MyComponent() {
-  // Use the React hook
-  const { data, isLoading } = useGetMessageQuery()
-
-  // Or fetch directly (for loaders, etc.)
-  await getMessageQuery.fetch()
+  const { data, isPending } = useActorQuery({
+    functionName: "get_message",
+  })
 
-  // Invalidate cache
-  await getMessageQuery.invalidate()
+  return <p>{isPending ? "Loading..." : data}</p>
 }
 ```
 
@@ -68,7 +66,7 @@ function MyComponent() {
 
 ### `init`
 
-Initialize ic-reactor in your project.
+Initialize the configuration file (`ic-reactor.json`).
 
 ```bash
 npx @ic-reactor/cli init [options]
@@ -78,189 +76,49 @@ Options:
   -o, --out-dir <path>   Output directory for generated hooks
 ```
 
-### `add`
-
-Add hooks for canister methods (from local .did file).
-
-```bash
-npx @ic-reactor/cli add [options]
-
-Options:
-  -c, --canister <name>      Canister to add hooks for
-  -m, --methods <methods...> Specific methods to generate
-  -a, --all                  Add hooks for all methods
-```
-
-### `fetch`
+### `sync`
 
-**Fetch Candid from a live canister** and generate hooks. No local .did file needed!
+Regenerate hooks and declarations based on your configuration and DID files.
 
 ```bash
-npx @ic-reactor/cli fetch [options]
+npx @ic-reactor/cli sync [options]
 
 Options:
-  -i, --canister-id <id>     Canister ID to fetch from
-  -n, --network <network>    Network: 'ic' or 'local' (default: ic)
-  --name <name>              Name for the canister in generated code
-  -m, --methods <methods...> Specific methods to generate
-  -a, --all                  Add hooks for all methods
-```
-
-**Example:**
-
-```bash
-# Fetch from IC mainnet
-npx @ic-reactor/cli fetch -i ryjl3-tyaaa-aaaaa-aaaba-cai
-
-# Fetch from local replica
-npx @ic-reactor/cli fetch -i bkyz2-fmaaa-aaaaa-qaaaq-cai -n local
+  -c, --canister <name>   Sync only a specific canister
 ```
 
 ### `list`
 
-List available methods from a canister.
+List all available methods from a canister's Candid definition.
 
 ```bash
-npx @ic-reactor/cli list [options]
-
-Options:
-  -c, --canister <name>   Canister to list methods from
-```
-
-### `sync`
-
-Regenerate hooks after DID file changes.
-
-```bash
-npx @ic-reactor/cli sync [options]
-
-Options:
-  -c, --canister <name>   Canister to sync (default: all)
+npx @ic-reactor/cli list -c <canister_name>
 ```
 
 ## Configuration
 
-### reactor.config.json
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/B3Pay/ic-reactor/main/packages/cli/schema.json",
-  "outDir": "src/canisters",
-  "canisters": {
-    "backend": {
-      "didFile": "./backend.did",
-      "clientManagerPath": "../../lib/client",
-      "useDisplayReactor": true
-    }
-  },
-  "generatedHooks": {
-    "backend": ["get_message", "set_message"]
-  }
-}
-```
-
-### Configuration Options
-
-| Option                               | Description                               |
-| ------------------------------------ | ----------------------------------------- |
-| `outDir`                             | Directory where hooks are generated       |
-| `canisters`                          | Canister configurations                   |
-| `canisters.<name>.didFile`           | Path to the `.did` file                   |
-| `canisters.<name>.clientManagerPath` | Import path to client manager             |
-| `canisters.<name>.useDisplayReactor` | Use DisplayReactor for type transforms    |
-| `generatedHooks`                     | Tracks which methods have hooks generated |
-
-## Generated File Structure
-
-```
-src/canisters/
-├── backend/
-│   ├── reactor.ts              # Shared reactor instance
-│   └── hooks/
-│       ├── index.ts            # Barrel exports
-│       ├── getMessageQuery.ts  # Query hook
-│       ├── setMessageMutation.ts # Mutation hook
-│       └── getPostsInfiniteQuery.ts # Infinite query
-```
-
-## Hook Types
-
-### Query (methods without side effects)
-
-```typescript
-// For methods WITH arguments - factory pattern
-export const getUserQuery = createQueryFactory(reactor, {
-  functionName: "get_user",
-})
-
-// Usage
-const query = getUserQuery([userId])
-const { data } = query.useQuery()
-
-// For methods WITHOUT arguments - static instance
-export const getConfigQuery = createQuery(reactor, {
-  functionName: "get_config",
-})
-
-// Usage
-const { data } = getConfigQuery.useQuery()
-await getConfigQuery.fetch()
-```
-
-### Mutation (methods with side effects)
-
-```typescript
-export const setMessageMutation = createMutation(reactor, {
-  functionName: "set_message",
-  invalidateQueries: [getMessageQuery.getQueryKey()],
-})
+The `ic-reactor.json` file supports the following options:
 
-// Usage
-const { mutate, isPending } = setMessageMutation.useMutation()
-mutate(["Hello, ICP!"])
-```
-
-### Infinite Query (paginated data)
-
-```typescript
-export const getPostsInfiniteQuery = createInfiniteQuery(reactor, {
-  functionName: "get_posts",
-  initialPageParam: 0,
-  getArgs: (cursor) => [{ cursor, limit: 10 }],
-  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
-})
-
-// Usage
-const { data, fetchNextPage, hasNextPage } =
-  getPostsInfiniteQuery.useInfiniteQuery()
-const allPosts = data?.pages.flatMap((page) => page.items) ?? []
-```
+| 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. |
 
-## Customization
+### Canister Config
 
-Since the code is generated into your project, you can:
-
-1. **Modify hook options** - Change staleTime, select transforms, etc.
-2. **Add custom logic** - Error handling, optimistic updates
-3. **Combine hooks** - Create composite hooks
-4. **Type overrides** - Adjust TypeScript types
-
-Example customization:
-
-```typescript
-// getMessageQuery.ts (generated, then customized)
-export const getMessageQuery = createQuery(reactor, {
-  functionName: "get_message",
-  staleTime: 30 * 1000, // Custom: 30 seconds
-  select: (data) => data.message.toUpperCase(), // Custom transform
-})
-```
+| 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.                       |
 
 ## Requirements
 
 - Node.js 18+
 - @ic-reactor/react 3.x
-- React 18+
+- TypeScript 5.0+
 
 ## License