fix: handle jiti MODULE_NOT_FOUND error and update docs (#44)

* fix: handle jiti MODULE_NOT_FOUND error and update docs

- isFileNotFound now treats MODULE_NOT_FOUND (from jiti) as file-not-found,
  so `abi-cli sync` without a config file shows a clean error message
- README updated to document name alias, --check flag, barrel file generation,
  and corrected generated output format (as const satisfies ClarityAbi)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add changeset for MODULE_NOT_FOUND fix

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: satoshai-dev

.changeset/fix-module-not-found.md

@@ -0,0 +1,5 @@
+---
+"@satoshai/abi-cli": patch
+---
+
+Fix jiti MODULE_NOT_FOUND error when running sync without a config file

README.md

@@ -30,14 +30,18 @@ abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01
 The generated file looks like:
 
 ```typescript
+import type { ClarityAbi } from '@stacks/transactions';
+
 // ABI for SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01
 // Generated by @satoshai/abi-cli
 
 export const abi = {
   "functions": [...],
   "variables": [...],
   ...
-} as const;
+} as const satisfies ClarityAbi;
+
+export type Abi = typeof abi;
 ```
 
 ### Output to stdout
@@ -100,13 +104,15 @@ Create `abi.config.json` in your project root:
   "format": "ts",
   "network": "mainnet",
   "contracts": [
-    { "id": "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01" },
-    { "id": "SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1" },
+    { "id": "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01", "name": "amm-pool" },
+    { "id": "SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1", "name": "arkadiko-swap" },
     { "id": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract", "network": "testnet" }
   ]
 }
 ```
 
+The `name` field controls the output filename. This decouples your imports from the on-chain contract ID — when you upgrade to a new contract version, change the `id` but keep the `name`. Your imports stay the same.
+
 Or use `abi.config.ts` for type-safe config with autocomplete:
 
 ```typescript
@@ -117,8 +123,8 @@ export default {
   format: 'ts',
   network: 'mainnet',
   contracts: [
-    { id: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01' },
-    { id: 'SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1' },
+    { id: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01', name: 'amm-pool' },
+    { id: 'SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1', name: 'arkadiko-swap' },
   ],
 } satisfies AbiConfig;
 ```
@@ -130,6 +136,22 @@ abi-cli sync
 # → reads abi.config.json (or .ts), writes all ABIs to outDir
 ```
 
+This generates:
+
+```
+src/abis/
+├── amm-pool.ts
+├── arkadiko-swap.ts
+└── index.ts          # barrel file with re-exports
+```
+
+The barrel file re-exports all ABIs with camelCase names:
+
+```typescript
+export { abi as ammPoolAbi } from './amm-pool.js';
+export { abi as arkadikoSwapAbi } from './arkadiko-swap.js';
+```
+
 Use `--config` / `-c` to point to a custom config path:
 
 ```bash
@@ -145,8 +167,28 @@ abi-cli sync --config ./configs/my-abis.json
 | `network` | `string` | no | `"mainnet"` | Default network for all contracts |
 | `contracts` | `ContractEntry[]` | yes | — | List of contracts to sync |
 | `contracts[].id` | `string` | yes | — | Contract ID in `address.name` format |
+| `contracts[].name` | `string` | no | contract name from ID | Alias for output filename and barrel export |
 | `contracts[].network` | `string` | no | top-level `network` | Per-contract network override |
 
+### Check — CI staleness detection
+
+Use `--check` to verify local files are in sync with on-chain ABIs without writing anything. Exits with code 1 if any files are stale or missing.
+
+```bash
+# Single contract
+abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 --check
+
+# All contracts from config
+abi-cli sync --check
+```
+
+Add it to your CI pipeline to catch stale types:
+
+```yaml
+- name: Check ABIs are up-to-date
+  run: npx @satoshai/abi-cli sync --check
+```
+
 ## Flags Reference
 
 ### `abi-cli fetch`
@@ -157,13 +199,15 @@ abi-cli sync --config ./configs/my-abis.json
 | `--output` | `-o` | `<contract-name>.<format>` | Output file path (single contract only) |
 | `--format` | `-f` | `ts` | Output format: `ts` or `json` |
 | `--stdout` | | `false` | Print to stdout instead of writing a file |
+| `--check` | | `false` | Check if local files match on-chain ABI (exit 1 if stale) |
 | `--help` | | | Show help |
 
 ### `abi-cli sync`
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
 | `--config` | `-c` | auto-discover | Path to config file |
+| `--check` | | `false` | Check if local files match on-chain ABIs (exit 1 if stale) |
 | `--help` | | | Show help |
 
 ## Programmatic API

src/config.ts

@@ -133,9 +133,7 @@ async function loadFile(filepath: string): Promise<AbiConfig> {
 }
 
 function isFileNotFound(err: unknown): boolean {
-  return (
-    err instanceof Error &&
-    'code' in err &&
-    (err as NodeJS.ErrnoException).code === 'ENOENT'
-  );
+  if (!(err instanceof Error) || !('code' in err)) return false;
+  const code = (err as NodeJS.ErrnoException).code;
+  return code === 'ENOENT' || code === 'MODULE_NOT_FOUND';
 }

tests/unit/config.test.ts

@@ -227,6 +227,23 @@ describe('loadConfig', () => {
     vi.doUnmock('jiti');
   });
 
+  it('treats MODULE_NOT_FOUND from jiti as file not found', async () => {
+    const notFound = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    vi.mocked(readFile).mockRejectedValue(notFound);
+
+    // jiti throws MODULE_NOT_FOUND instead of ENOENT
+    const moduleNotFound = Object.assign(new Error('Cannot find module'), { code: 'MODULE_NOT_FOUND' });
+    const mockImport = vi.fn().mockRejectedValue(moduleNotFound);
+    const mockJiti = vi.fn().mockReturnValue({ import: mockImport });
+    vi.doMock('jiti', () => ({ default: mockJiti }));
+
+    const { loadConfig: loadConfigFresh } = await import('../../src/config.js');
+
+    await expect(loadConfigFresh()).rejects.toThrow('No config file found');
+
+    vi.doUnmock('jiti');
+  });
+
   it('throws on invalid JSON content', async () => {
     vi.mocked(readFile).mockResolvedValueOnce('not json {{{');