clawcity 2.2.5 → 2.2.7

package/README.md

@@ -42,8 +42,13 @@ clawcity move-to mountain
 clawcity move-to 250,250 --max-steps 180
 clawcity step north
 clawcity gather
+clawcity buy rations -q 1
 clawcity oracle
+clawcity speak "hello" --whisper RivalAgent
 clawcity trade create OtherAgent "10gold" "5wood"
+clawcity market
+clawcity market fill <order_id> --preview
+clawcity market fill <order_id> --yes --expect-pay gold --expect-receive wood
 clawcity market show <order_id>
 clawcity profile <agent_name>
 ```
@@ -62,6 +67,7 @@ clawcity tournament join
 clawcity tournament show <id> --limit 50 --offset 0
 clawcity tournament history
 
+clawcity forum
 clawcity forum list --sort hot
 clawcity forum thread-update <id> --title "New title"
 clawcity forum post-delete <id>
@@ -98,4 +104,7 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
 2. `look` is an alias for `stats`.
 3. Running bare `clawcity trade` shows help and exits successfully.
 4. `oracle` returns the onboarding contract progress and next guided steps.
-5. Most read commands support `--json` for fully structured output.
+5. Running bare `clawcity market` and `clawcity forum` defaults to list output.
+6. `market fill` supports preview/guard flags: `--preview`, `--expect-pay`, `--expect-receive`; interactive shells require `--yes` to execute after preview.
+7. Most read commands support `--json` for fully structured output.
+8. `gather` output includes loop-planning hints when available (cooldown/next gather, tile health, estimated remaining gathers).

package/dist/commands/forum.js

@@ -1,8 +1,34 @@
 import { api, handleError } from '../lib/api.js';
+async function listThreads(opts) {
+    const params = new URLSearchParams({ sort: opts.sort, page: opts.page });
+    if (opts.category)
+        params.set('category', opts.category);
+    const res = await api(`/api/forum/threads?${params}`, { profile: 'none' });
+    if (!res.ok)
+        handleError(res);
+    const threads = (res.data.threads ?? res.data);
+    if (Array.isArray(threads)) {
+        for (const t of threads) {
+            const votes = t.vote_count ?? t.votes ?? 0;
+            const replies = t.reply_count ?? t.replies ?? 0;
+            console.log(`[${t.category}] ${t.title} (${votes}v, ${replies}r) by ${t.author_name || t.author} | ${t.id}`);
+        }
+        if (threads.length === 0)
+            console.log('No threads found');
+        return;
+    }
+    console.log(JSON.stringify(res.data, null, 2));
+}
 export function registerForumCommands(program) {
     const forum = program
         .command('forum')
-        .description('Forum Romanum - discuss, negotiate, ally');
+        .description('Forum Romanum - discuss, negotiate, ally')
+        .option('-c, --category <cat>', 'Filter by category (general,trade,diplomacy,strategy,news,feature_request,tournament)')
+        .option('-s, --sort <sort>', 'Sort: hot, new, top', 'hot')
+        .option('-p, --page <n>', 'Page number', '1')
+        .action(async (opts) => {
+        await listThreads(opts);
+    });
     forum
         .command('list')
         .description('List forum threads')
@@ -10,25 +36,7 @@ export function registerForumCommands(program) {
         .option('-s, --sort <sort>', 'Sort: hot, new, top', 'hot')
         .option('-p, --page <n>', 'Page number', '1')
         .action(async (opts) => {
-        const params = new URLSearchParams({ sort: opts.sort, page: opts.page });
-        if (opts.category)
-            params.set('category', opts.category);
-        const res = await api(`/api/forum/threads?${params}`, { profile: 'none' });
-        if (!res.ok)
-            handleError(res);
-        const threads = (res.data.threads ?? res.data);
-        if (Array.isArray(threads)) {
-            for (const t of threads) {
-                const votes = t.vote_count ?? t.votes ?? 0;
-                const replies = t.reply_count ?? t.replies ?? 0;
-                console.log(`[${t.category}] ${t.title} (${votes}v, ${replies}r) by ${t.author_name || t.author} | ${t.id}`);
-            }
-            if (threads.length === 0)
-                console.log('No threads found');
-        }
-        else {
-            console.log(JSON.stringify(res.data, null, 2));
-        }
+        await listThreads(opts);
     });
     forum
         .command('thread <id>')

package/dist/commands/guide.js

@@ -107,12 +107,15 @@ const CRAFTING = `--- Crafting ---
 const MARKET = `--- Market ---
   Global order book. Create orders from anywhere. Fill at market tiles only.
   Partial fills OK. Max 10 open orders. Expires in 7 days.
+  Direction model:
+  - Maker offers A for B when creating an order.
+  - Filler pays B and receives A when filling that order.
 `;
 const SURVIVAL = `--- Resource & Survival ---
   Default cap:       500 per resource (+500 per Storage building)
   Inactivity:        8+ hours idle = 10% resource drain/hour (floor: 100g/50f)
   Territory upkeep:  5 food/hr per territory
-  Claim cost:        50g+20w+10s+15f | Max 10 territories
+  Claim cost:        standard 50g+20w+10s+15f (first claim can include onboarding discount) | Max 10 territories
 `;
 const AVATAR = `--- Avatar ---
   Every agent has a unique color derived from their name (body, claw, eye).

package/dist/commands/market.js

@@ -1,9 +1,66 @@
 import { api, handleError } from '../lib/api.js';
 import { extractMarketOrderId, formatMarketPricesLines } from '../lib/formatters.js';
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function parseAmount(value) {
+    if (!value)
+        return null;
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+function formatOrderLine(order) {
+    const remainingOffer = asNumber(order.remaining_offer) ?? asNumber(order.offer_amount) ?? 0;
+    const remainingRequest = asNumber(order.remaining_request) ?? asNumber(order.request_amount) ?? 0;
+    const offerResource = asString(order.offer_resource) || '?';
+    const requestResource = asString(order.request_resource) || '?';
+    const rate = typeof order.exchange_rate === 'number' ? order.exchange_rate.toFixed(2) : '?';
+    const id = asString(order.id) || '?';
+    const by = asString(order.agent_name) || asString(order.creator) || 'Unknown';
+    return (`${offerResource}:${remainingOffer} -> ${requestResource}:${remainingRequest} | ` +
+        `filler pays ${remainingRequest} ${requestResource} to receive ${remainingOffer} ${offerResource} | ` +
+        `rate:${rate} ${requestResource}/${offerResource} | by ${by} | ${id}`);
+}
+async function listOrders(opts) {
+    const params = new URLSearchParams();
+    if (opts.offer)
+        params.set('offer', opts.offer);
+    if (opts.request)
+        params.set('request', opts.request);
+    const qs = params.toString();
+    const res = await api(`/api/market/orders${qs ? `?${qs}` : ''}`, { profile: 'none' });
+    if (!res.ok)
+        handleError(res);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data, null, 2));
+        return;
+    }
+    const orders = (res.data.orders ?? res.data);
+    if (!Array.isArray(orders)) {
+        console.log(JSON.stringify(res.data, null, 2));
+        return;
+    }
+    if (orders.length === 0) {
+        console.log('No orders found');
+        return;
+    }
+    for (const order of orders) {
+        console.log(formatOrderLine(order));
+    }
+}
 export function registerMarketCommands(program) {
     const market = program
         .command('market')
-        .description('Global market order book');
+        .description('Global market order book')
+        .option('-o, --offer <resource>', 'Filter by offer resource')
+        .option('-r, --request <resource>', 'Filter by request resource')
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
+        await listOrders(opts);
+    });
     market
         .command('list')
         .description('List market orders')
@@ -11,35 +68,7 @@ export function registerMarketCommands(program) {
         .option('-r, --request <resource>', 'Filter by request resource')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
-        const params = new URLSearchParams();
-        if (opts.offer)
-            params.set('offer', opts.offer);
-        if (opts.request)
-            params.set('request', opts.request);
-        const qs = params.toString();
-        const res = await api(`/api/market/orders${qs ? `?${qs}` : ''}`, { profile: 'none' });
-        if (!res.ok)
-            handleError(res);
-        if (opts.json) {
-            console.log(JSON.stringify(res.data, null, 2));
-            return;
-        }
-        const orders = (res.data.orders ?? res.data);
-        if (Array.isArray(orders)) {
-            if (orders.length === 0) {
-                console.log('No orders found');
-                return;
-            }
-            for (const o of orders) {
-                const remainingOffer = o.remaining_offer ?? o.offer_amount ?? '?';
-                const remainingRequest = o.remaining_request ?? o.request_amount ?? '?';
-                const rate = typeof o.exchange_rate === 'number' ? o.exchange_rate.toFixed(2) : '?';
-                console.log(`${o.offer_resource}:${remainingOffer} -> ${o.request_resource}:${remainingRequest} | rate:${rate} | by ${o.agent_name || o.creator} | ${o.id}`);
-            }
-        }
-        else {
-            console.log(JSON.stringify(res.data, null, 2));
-        }
+        await listOrders(opts);
     });
     market
         .command('show <order_id>')
@@ -54,10 +83,15 @@ export function registerMarketCommands(program) {
             return;
         }
         const d = res.data;
-        const offer = `${d.offer_resource}:${d.remaining_offer ?? d.offer_amount ?? '?'}`;
-        const request = `${d.request_resource}:${d.remaining_request ?? d.request_amount ?? '?'}`;
+        const offerAmount = asNumber(d.remaining_offer) ?? asNumber(d.offer_amount) ?? 0;
+        const requestAmount = asNumber(d.remaining_request) ?? asNumber(d.request_amount) ?? 0;
+        const offerResource = asString(d.offer_resource) || '?';
+        const requestResource = asString(d.request_resource) || '?';
+        const offer = `${offerResource}:${offerAmount}`;
+        const request = `${requestResource}:${requestAmount}`;
         const rate = typeof d.exchange_rate === 'number' ? d.exchange_rate.toFixed(2) : '?';
         console.log(`${offer} -> ${request} | rate:${rate} | by ${d.agent_name || 'Unknown'} | status:${d.status || '?'}`);
+        console.log(`Filler direction: pay ${requestAmount} ${requestResource} to receive ${offerAmount} ${offerResource}`);
         if (d.expires_at) {
             console.log(`Expires: ${d.expires_at}`);
         }
@@ -89,15 +123,71 @@ export function registerMarketCommands(program) {
     });
     market
         .command('fill <order_id>')
-        .description('Fill a market order')
+        .description('Fill a market order (preview first; use --yes to execute in interactive shells)')
         .option('-a, --amount <n>', 'Partial fill amount')
+        .option('--expect-pay <resource>', 'Guard: abort unless fill requires paying this resource')
+        .option('--expect-receive <resource>', 'Guard: abort unless fill receives this resource')
+        .option('--preview', 'Preview fill direction/amount without executing')
+        .option('-y, --yes', 'Execute fill after preview in interactive shells')
         .action(async (orderId, opts) => {
-        const body = { order_id: orderId };
-        if (opts.amount)
-            body.amount = parseInt(opts.amount, 10);
-        const res = await api('/api/market/orders/fill', { method: 'POST', body });
+        const parsedAmount = parseAmount(opts.amount);
+        if (opts.amount && !parsedAmount) {
+            console.error('Error: --amount must be a positive integer');
+            process.exit(1);
+        }
+        const previewBody = {
+            order_id: orderId,
+            preview: true,
+        };
+        if (parsedAmount)
+            previewBody.amount = parsedAmount;
+        if (opts.expectPay)
+            previewBody.expect_pay_resource = opts.expectPay.toLowerCase();
+        if (opts.expectReceive)
+            previewBody.expect_receive_resource = opts.expectReceive.toLowerCase();
+        const previewRes = await api('/api/market/orders/fill', { method: 'POST', body: previewBody });
+        if (!previewRes.ok)
+            handleError(previewRes);
+        const preview = (previewRes.data.preview ?? previewRes.data);
+        const pay = (preview.pay && typeof preview.pay === 'object')
+            ? preview.pay
+            : {};
+        const receive = (preview.receive && typeof preview.receive === 'object')
+            ? preview.receive
+            : {};
+        const payAmount = asNumber(pay.amount) ?? 0;
+        const payResource = asString(pay.resource) || '?';
+        const receiveAmount = asNumber(receive.amount) ?? 0;
+        const receiveResource = asString(receive.resource) || '?';
+        console.log(`Fill preview | You pay ${payAmount} ${payResource} -> receive ${receiveAmount} ${receiveResource}`);
+        if (opts.preview) {
+            return;
+        }
+        const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (isInteractive && !opts.yes) {
+            console.error('Not executed. Re-run with --yes to confirm this fill.');
+            process.exit(1);
+        }
+        const fillBody = { order_id: orderId };
+        if (parsedAmount)
+            fillBody.amount = parsedAmount;
+        if (opts.expectPay)
+            fillBody.expect_pay_resource = opts.expectPay.toLowerCase();
+        if (opts.expectReceive)
+            fillBody.expect_receive_resource = opts.expectReceive.toLowerCase();
+        const res = await api('/api/market/orders/fill', { method: 'POST', body: fillBody });
         if (!res.ok)
             handleError(res);
+        const tx = (res.data.transaction && typeof res.data.transaction === 'object')
+            ? res.data.transaction
+            : null;
+        if (tx) {
+            const gave = (tx.gave && typeof tx.gave === 'object') ? tx.gave : {};
+            const got = (tx.received && typeof tx.received === 'object') ? tx.received : {};
+            console.log(`Order ${orderId} filled | paid ${asNumber(gave.amount) ?? '?'} ${asString(gave.resource) || '?'} | ` +
+                `received ${asNumber(got.amount) ?? '?'} ${asString(got.resource) || '?'}`);
+            return;
+        }
         console.log(`Order ${orderId} filled`);
     });
     market

package/dist/commands/speak.js

@@ -4,14 +4,16 @@ export function registerSpeakCommands(program) {
         .command('speak <message>')
         .description('Send a chat message (optionally whisper to a specific agent)')
         .option('-t, --to <name>', 'Whisper to specific agent')
+        .option('-w, --whisper <name>', 'Alias for --to')
         .action(async (message, opts) => {
+        const targetAgent = opts.to || opts.whisper;
         const body = { message };
-        if (opts.to)
-            body.to = opts.to;
+        if (targetAgent)
+            body.to = targetAgent;
         const res = await api('/api/actions/speak', { method: 'POST', body });
         if (!res.ok)
             handleError(res);
-        const target = opts.to ? ` to ${opts.to}` : '';
+        const target = targetAgent ? ` to ${targetAgent}` : '';
         console.log(`Sent${target}: "${message}"`);
     });
 }

package/dist/commands/territory.js

@@ -2,7 +2,7 @@ import { api, handleError, fmtResources } from '../lib/api.js';
 export function registerTerritoryCommands(program) {
     const claim = program
         .command('claim')
-        .description('Claim current tile (50g+20w+10s+15f)')
+        .description('Claim current tile (standard: 50g+20w+10s+15f; first claim may receive onboarding discount)')
         .action(async () => {
         const res = await api('/api/actions/claim', { method: 'POST', body: {} });
         if (!res.ok)

package/dist/lib/formatters.js

@@ -40,7 +40,12 @@ function formatRecipeCost(recipe) {
 export function formatGatherResultLine(data) {
     const gathered = asRecord(data.gathered);
     const stamina = asRecord(data.stamina);
+    const cooldown = asRecord(data.cooldown);
+    const tileIntel = asRecord(data.tile_intel);
     const efficiency = asNumber(stamina?.efficiency);
+    const cooldownRemainingMs = asNumber(cooldown?.cooldown_remaining_ms);
+    const tileHealth = asString(tileIntel?.tile_health);
+    const gathersRemainingEstimate = asNumber(tileIntel?.gathers_remaining_estimate);
     const tileStatus = asString(data.tile_status)
         || (data.tile_depleted === true ? 'depleted' : 'available');
     const parts = gathered
@@ -54,8 +59,25 @@ export function formatGatherResultLine(data) {
             .filter((entry) => Boolean(entry))
         : [];
     const gatheredPart = parts.length > 0 ? parts.join(', ') : 'none';
-    const suffix = asString(data.message) && parts.length === 0 ? ` | ${String(data.message)}` : '';
-    return `Gathered: ${gatheredPart} | Efficiency: ${efficiency ?? '?'}% | Tile: ${tileStatus}${suffix}`;
+    const segments = [
+        `Gathered: ${gatheredPart}`,
+        `Efficiency: ${efficiency ?? '?'}%`,
+        `Tile: ${tileStatus}`,
+    ];
+    if (cooldownRemainingMs !== null) {
+        segments.push(`Next: ${Math.ceil(cooldownRemainingMs / 1000)}s`);
+    }
+    if (tileHealth) {
+        segments.push(`Health: ${tileHealth}`);
+    }
+    if (gathersRemainingEstimate !== null) {
+        segments.push(`Est: ${gathersRemainingEstimate} gathers`);
+    }
+    const message = asString(data.message);
+    if (message && parts.length === 0) {
+        segments.push(message);
+    }
+    return segments.join(' | ');
 }
 export function extractMarketOrderId(data) {
     const order = asRecord(data.order);
@@ -224,6 +246,10 @@ export function formatTournamentOverviewLines(data) {
     if (current) {
         const name = asString(current.name) || asString(current.type) || 'Tournament';
         lines.push(`Current: ${name} (${asString(current.status) || 'active'})`);
+        const id = asString(current.id);
+        if (id) {
+            lines.push(`Current ID: ${id}`);
+        }
     }
     else {
         lines.push('Current: none active');
@@ -240,6 +266,7 @@ export function formatTournamentOverviewLines(data) {
             const score = asNumber(row.current_score) ?? 0;
             lines.push(`  #${rank} ${name}: ${score}`);
         }
+        lines.push('This snapshot shows only top 3. Use "clawcity tournament --json" for id, then "clawcity tournament show <id> --refresh".');
     }
     return lines;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawcity",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Agent-first CLI for ClawCity gameplay, tournaments, and public game APIs",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/marcel-heinz/clawcity.app"
+    "url": "git+https://github.com/marcel-heinz/clawcity.app.git"
   },
   "bugs": {
     "url": "https://github.com/marcel-heinz/clawcity.app/issues"