@reppo/cli 0.1.0

package/dist/state/idempotency.js

@@ -0,0 +1,173 @@
+/**
+ * Idempotency layer. Two-phase write protocol so an agent retry that
+ * fires *during* a transaction (after submit, before receipt) sees the
+ * pending record and short-circuits instead of double-spending.
+ *
+ *   1. begin(key, command, args)            — write { status: 'pending' }
+ *   2. markSubmitted(key, command, args, tx)— write { status: 'submitted', txHash }
+ *   3. markConfirmed(key, command, args, r) — write { status: 'confirmed', result, txHash }
+ *      OR
+ *      markFailed(key, command, args, err)  — write { status: 'failed', result: { error } }
+ *
+ * Every helper takes the full args object so a deterministic fingerprint
+ * can be stored on first write. Re-using one --idempotency-key with a
+ * different intent (e.g. vote pod 39 like → vote pod 41 dislike) is
+ * rejected with `IDEMPOTENCY_ARGS_MISMATCH` instead of silently
+ * returning the wrong cached result.
+ *
+ * Callers should pattern-match `getIdempotent(key, command, args)`
+ * BEFORE doing work:
+ *   - null         → fresh, proceed
+ *   - 'confirmed'  → return cached result
+ *   - 'submitted'  → return cached txHash; the agent can poll the tx
+ *   - 'pending'    → another invocation is mid-flight; refuse with code
+ *   - 'failed'     → previous attempt failed; refuse OR allow retry under
+ *                    a fresh key (caller policy)
+ */
+import { createHash } from 'node:crypto';
+import { getIdempotent as readEntry, upsertIdempotent, } from './db.js';
+import { cliError } from '../output/format.js';
+/**
+ * SHA-256 of the canonicalized JSON of the args object. Object keys are
+ * sorted so {a:1,b:2} and {b:2,a:1} fingerprint identically; bigints
+ * are stringified so they survive JSON.stringify; nested arrays/objects
+ * recurse. The output is the only thing the cache compares — small
+ * representation choices below matter for matching across runs.
+ */
+export function fingerprintArgs(args) {
+    const replacer = (_key, value) => {
+        if (typeof value === 'bigint')
+            return value.toString();
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const sorted = {};
+            for (const k of Object.keys(value).sort()) {
+                sorted[k] = value[k];
+            }
+            return sorted;
+        }
+        return value;
+    };
+    const canonical = JSON.stringify(args, replacer);
+    return createHash('sha256').update(canonical).digest('hex');
+}
+export async function getIdempotent(key, command, args) {
+    const entry = await readEntry(key);
+    if (!entry)
+        return null;
+    if (entry.command !== command) {
+        throw cliError('IDEMPOTENCY_COMMAND_MISMATCH', `idempotency key "${key}" was previously used by command "${entry.command}", ` +
+            `not "${command}". Use a unique key per (command, intent) pair.`);
+    }
+    const fp = fingerprintArgs(args);
+    // Pre-v0.2 cache entries lack argsFingerprint. Refuse with a clear
+    // migration error rather than silently treating any args as a match.
+    if (!entry.argsFingerprint) {
+        throw cliError('IDEMPOTENCY_LEGACY_ENTRY', `idempotency key "${key}" predates v0.2's args-fingerprint check and cannot be safely re-used.`, 'Delete ~/.reppo/cli-state.json (or set REPPO_STATE_PATH to a fresh file) to clear the legacy cache, then retry with a new --idempotency-key.');
+    }
+    if (entry.argsFingerprint !== fp) {
+        throw cliError('IDEMPOTENCY_ARGS_MISMATCH', `idempotency key "${key}" was previously used with different args ` +
+            `(fingerprint ${entry.argsFingerprint.slice(0, 12)}…) and is now being read with new args ` +
+            `(fingerprint ${fp.slice(0, 12)}…).`, 'A given idempotency key represents a single intent. Use a fresh key when the args change.');
+    }
+    return entry;
+}
+/**
+ * Inspect the idempotency cache and decide whether the caller should
+ * proceed with a write. Lifts the cache-decision logic that previously
+ * lived inline in `vote.ts` so every write command shares the same
+ * policy:
+ *   - dry-run: never consult or mutate the cache (sim is read-only;
+ *     persisting a "submitted" record would let a sim poison the cache
+ *     for the next real call).
+ *   - confirmed: short-circuit with the cached result.
+ *   - submitted: short-circuit with the cached tx hash; user polls.
+ *   - pending:   refuse — another invocation is mid-flight.
+ *   - failed + txHash: refuse — re-broadcasting under the same key would
+ *     pay gas for a second doomed attempt; force a fresh key.
+ *   - failed + no txHash: pre-submit failure, safe to retry: 'proceed'.
+ *
+ * The result type `R` matches the shape the command stores via
+ * `markConfirmed` (e.g. `{ txHash, podId, ..., basescanUrl }` for vote).
+ * Cached results are typed as the caller's `R`; runtime shape is whatever
+ * the original `markConfirmed` recorded.
+ */
+export async function peekIdempotent(key, command, args, isDryRun) {
+    if (!key || isDryRun)
+        return { kind: 'proceed' };
+    const cached = await getIdempotent(key, command, args);
+    if (!cached)
+        return { kind: 'proceed' };
+    switch (cached.status) {
+        case 'confirmed':
+            return { kind: 'return-confirmed', result: cached.result, txHash: cached.txHash };
+        case 'submitted':
+            return { kind: 'return-submitted', result: cached.result, txHash: cached.txHash };
+        case 'pending':
+            throw cliError('IDEMPOTENCY_IN_FLIGHT', `Idempotency key "${key}" is in 'pending' state — another invocation is mid-flight.`, 'Wait for the in-flight invocation to finish, or use a fresh key.');
+        case 'failed':
+            if (cached.txHash) {
+                throw cliError('IDEMPOTENCY_FAILED_AFTER_BROADCAST', `Idempotency key "${key}" previously broadcast tx ${cached.txHash} which failed. ` +
+                    `Refusing to re-broadcast under the same key.`, 'Use a fresh --idempotency-key for the retry, and inspect the prior tx on the block explorer to understand the failure.');
+            }
+            // Pre-submit failure (e.g. validation error). Safe to retry under
+            // the same key; fall through.
+            return { kind: 'proceed' };
+    }
+}
+export async function begin(key, command, args) {
+    const now = Date.now();
+    await upsertIdempotent(key, {
+        command,
+        argsFingerprint: fingerprintArgs(args),
+        status: 'pending',
+        result: {},
+        txHash: null,
+        createdAt: now,
+        updatedAt: now,
+    });
+}
+export async function markSubmitted(key, command, args, txHash) {
+    const now = Date.now();
+    await upsertIdempotent(key, {
+        command,
+        argsFingerprint: fingerprintArgs(args),
+        status: 'submitted',
+        result: { txHash },
+        txHash,
+        createdAt: now,
+        updatedAt: now,
+    });
+}
+export async function markConfirmed(key, command, args, result, txHash) {
+    const now = Date.now();
+    await upsertIdempotent(key, {
+        command,
+        argsFingerprint: fingerprintArgs(args),
+        status: 'confirmed',
+        result,
+        txHash,
+        createdAt: now,
+        updatedAt: now,
+    });
+}
+/**
+ * Mark an idempotency entry as failed. Pass `txHash` when the failure
+ * happened *after* the tx was broadcast (e.g. on-chain revert, receipt
+ * timeout) so the cached entry retains the hash for forensics + so the
+ * "same-key retry on failed" guard in callers can distinguish pre-submit
+ * failures (safe to retry) from post-submit failures (must not retry —
+ * the tx already executed and may have side-effects).
+ */
+export async function markFailed(key, command, args, error, txHash = null) {
+    const now = Date.now();
+    await upsertIdempotent(key, {
+        command,
+        argsFingerprint: fingerprintArgs(args),
+        status: 'failed',
+        result: txHash ? { error, txHash } : { error },
+        txHash,
+        createdAt: now,
+        updatedAt: now,
+    });
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/state/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/state/idempotency.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@reppo/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for Reppo — mint pods, vote, lock REPPO, manage datanets. Built for AI agents.",
+  "license": "MIT",
+  "author": "Reppo Labs",
+  "homepage": "https://github.com/Reppo-Labs/reppo-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Reppo-Labs/reppo-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Reppo-Labs/reppo-cli/issues"
+  },
+  "keywords": [
+    "reppo",
+    "cli",
+    "base",
+    "agents",
+    "web3",
+    "datanet"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "reppo": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/bin.ts",
+    "lint": "eslint src --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "clipanion": "^4.0.0-rc.4",
+    "proper-lockfile": "^4.1.2",
+    "typanion": "^3.14.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "@vitest/coverage-v8": "^4.1.5",
+    "eslint": "^10.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.59.2",
+    "vitest": "^4.0.0"
+  }
+}