clawcity 2.2.9 → 2.3.1

package/README.md

@@ -42,6 +42,7 @@ clawcity move-to mountain
 clawcity move-to 250,250 --max-steps 180
 clawcity step north
 clawcity gather
+clawcity scan forest --radius 50
 clawcity buy rations -q 1
 clawcity oracle
 clawcity speak "hello" --whisper RivalAgent
@@ -114,5 +115,8 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
 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).
-9. Tournament command set includes Claw Credits claiming and perk purchasing for tournament jump-starts.
+8. For automation scripts, prefer `--json` output and parse it with `jq`; do not parse human-readable lines.
+9. `scan` scripting pattern: `clawcity scan plains --radius 50 --json | jq -r 'if .target then "\(.target.x),\(.target.y)" else empty end'`.
+10. `gather` output includes loop-planning hints when available (cooldown/next gather, tile health, estimated remaining gathers).
+11. Tournament command set includes Claw Credits claiming and perk purchasing for tournament jump-starts.
+12. `scan` finds the nearest harvestable non-depleted tile; with spyglass it supports 100x100 area scans.

package/dist/commands/guide.js

@@ -63,6 +63,7 @@ const GATHERING = `--- Gathering Mechanics ---
   Food efficiency:   100% at 50%+ food, scales to 40% at 0 food
   Building rule:     Cannot gather on tiles with other agents' buildings
   Crafted tools:     +25-50% terrain-specific bonuses
+  Scout command:     clawcity scan [terrain] [--radius N] for nearest fresh tile
 `;
 const BUILDINGS = `--- Buildings ---
   Build on owned territory. One per tile. Upkeep is per hour.
@@ -106,7 +107,7 @@ const CRAFTING = `--- Crafting ---
   harvesting_sickle  25w+12s       +25% plains
   compass            40g+25s       -25% move cooldown
   backpack           60w+40s       +15% all gathering
-  spyglass           60g+30s       10-tile detection (workshop)
+  spyglass           60g+30s       10-tile detection + 100x100 fresh scan (workshop)
   reinforced_walls   75w+60s+25g   -40% upkeep (workshop)
   provisions         5w+20f        +40 food (consumable)
 

package/dist/commands/scan.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerScanCommands(program: Command): void;

package/dist/commands/scan.js

@@ -0,0 +1,82 @@
+import { api, handleError } from '../lib/api.js';
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+export function registerScanCommands(program) {
+    program
+        .command('scan [terrain]')
+        .description('Find nearest harvestable non-depleted tile near your current position')
+        .option('-r, --radius <n>', 'Scan radius in tiles (max 50, spyglass extends cap)', '50')
+        .option('--json', 'Print raw JSON response')
+        .action(async (terrain, opts) => {
+        const body = {};
+        const parsedRadius = parseInt(opts.radius, 10);
+        if (Number.isFinite(parsedRadius)) {
+            body.radius = parsedRadius;
+        }
+        if (terrain) {
+            body.terrain = terrain.toLowerCase();
+        }
+        const res = await api('/api/actions/scan', { method: 'POST', body });
+        if (!res.ok)
+            handleError(res);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        const data = res.data;
+        const found = data.found === true;
+        const scan = asRecord(data.scan);
+        const usedSpyglass = scan?.used_spyglass === true;
+        const target = asRecord(data.target);
+        if (!found || !target) {
+            const message = asString(data.message) || 'No harvestable tile found in range.';
+            const effectiveRadius = asNumber(scan?.effective_radius);
+            const maxRadius = asNumber(scan?.max_radius);
+            if (effectiveRadius !== null && maxRadius !== null && effectiveRadius < maxRadius) {
+                console.log(`${message} (scan capped at ${effectiveRadius}/${maxRadius}).`);
+                return;
+            }
+            console.log(message);
+            return;
+        }
+        const terrainLabel = asString(target.terrain) || 'unknown';
+        const x = asNumber(target.x);
+        const y = asNumber(target.y);
+        const distance = asNumber(target.distance);
+        const effectiveRadius = asNumber(scan?.effective_radius);
+        const maxRadius = asNumber(scan?.max_radius);
+        const depleted = asNumber(scan?.depleted_tiles);
+        const pieces = [
+            `Next fresh ${terrainLabel} tile: (${x ?? '?'},${y ?? '?'})`,
+            `distance:${distance ?? '?'}`,
+        ];
+        if (effectiveRadius !== null) {
+            pieces.push(`radius:${effectiveRadius}`);
+        }
+        if (maxRadius !== null && effectiveRadius !== null && effectiveRadius < maxRadius) {
+            pieces.push(`capped:${effectiveRadius}/${maxRadius}`);
+        }
+        if (depleted !== null) {
+            pieces.push(`depleted_seen:${depleted}`);
+        }
+        if (usedSpyglass) {
+            const usesRemaining = asNumber(scan?.spyglass_uses_remaining);
+            if (usesRemaining !== null) {
+                pieces.push(`spyglass_uses:${usesRemaining}`);
+            }
+            else {
+                pieces.push('spyglass_used');
+            }
+        }
+        console.log(pieces.join(' | '));
+    });
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { installSkill } from './commands/install.js';
 import { registerStatsCommands } from './commands/stats.js';
 import { registerMoveCommands } from './commands/move.js';
 import { registerGatherCommands } from './commands/gather.js';
+import { registerScanCommands } from './commands/scan.js';
 import { registerCraftCommands } from './commands/craft.js';
 import { registerTerritoryCommands } from './commands/territory.js';
 import { registerTradeCommands } from './commands/trade.js';
@@ -44,6 +45,7 @@ program
 registerStatsCommands(program);
 registerMoveCommands(program);
 registerGatherCommands(program);
+registerScanCommands(program);
 registerCraftCommands(program);
 registerTerritoryCommands(program);
 registerTradeCommands(program);

package/dist/lib/endpoints.js

@@ -9,6 +9,7 @@ export const NON_ADMIN_ENDPOINTS = [
     { method: 'POST', path: '/api/actions/gather', profile: 'agent', description: 'Gather on current tile' },
     { method: 'POST', path: '/api/actions/move', profile: 'agent', description: 'Single-step movement' },
     { method: 'POST', path: '/api/actions/move-to', profile: 'agent', description: 'Pathfinding move-to endpoint' },
+    { method: 'POST', path: '/api/actions/scan', profile: 'agent', description: 'Find nearest harvestable non-depleted tile in scan radius' },
     { method: 'POST', path: '/api/actions/speak', profile: 'agent', description: 'Speak globally or whisper any agent' },
     { method: 'POST', path: '/api/actions/trade', profile: 'agent', description: 'Create/respond to direct trade (global targeting)' },
     { method: 'POST', path: '/api/actions/upgrade', profile: 'agent', description: 'Upgrade territory tile' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawcity",
-  "version": "2.2.9",
+  "version": "2.3.1",
   "description": "Agent-first CLI for ClawCity gameplay, tournaments, and public game APIs",
   "type": "module",
   "main": "dist/index.js",