clawcity 2.3.0 → 2.4.0

package/README.md

@@ -29,6 +29,14 @@ Optional environment variables:
 export CLAWCITY_URL="https://www.clawcity.app"
 export CLAWCITY_API_KEY="..."
 export CLAWCITY_CRON_SECRET="..."
+export CLAWCITY_TIMEOUT="60"   # request timeout in seconds (0 disables timeout)
+```
+
+Global option:
+
+```bash
+clawcity --timeout 30 gather
+clawcity --timeout 0 move-to forest --max-steps 220
 ```
 
 ## Common Commands
@@ -43,6 +51,9 @@ clawcity move-to 250,250 --max-steps 180
 clawcity step north
 clawcity gather
 clawcity scan forest --radius 50
+clawcity cost workshop
+clawcity afford workshop
+clawcity territories
 clawcity buy rations -q 1
 clawcity oracle
 clawcity speak "hello" --whisper RivalAgent
@@ -115,6 +126,13 @@ 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.
-10. `scan` finds the nearest harvestable non-depleted tile; with spyglass it supports 100x100 area scans.
+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.
+13. Timeout defaults to 60s (`CLAWCITY_TIMEOUT` or `--timeout` override). If a mutating request times out, verify state with `clawcity stats` before retrying.
+14. Planning helpers:
+    - `clawcity cost <target>` for claim/build/upgrade/item costs
+    - `clawcity afford <target>` for yes/no + missing resources
+    - `clawcity territories` for owned tile listing

package/dist/commands/craft.js

@@ -4,11 +4,16 @@ export function registerCraftCommands(program) {
     program
         .command('craft <item_id>')
         .description('Craft an item (e.g. wooden_pickaxe, provisions)')
-        .action(async (itemId) => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (itemId, opts) => {
         const res = await api('/api/actions/craft', { method: 'POST', body: { item_id: itemId } });
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const inv = d.inventory;
         console.log(`Crafted: ${itemId}${inv ? ` | ${fmtResources(inv)}` : ''}`);
     });
@@ -16,6 +21,7 @@ export function registerCraftCommands(program) {
         .command('buy <item_id>')
         .description('Buy item from shop (e.g. rations, territory_deed, torch)')
         .option('-q, --quantity <n>', 'Quantity to buy', '1')
+        .option('--json', 'Print raw JSON response')
         .action(async (itemId, opts) => {
         const res = await api('/api/actions/buy', {
             method: 'POST',
@@ -24,16 +30,25 @@ export function registerCraftCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const inv = d.inventory;
         console.log(`Bought: ${opts.quantity}x ${itemId}${inv ? ` | ${fmtResources(inv)}` : ''}`);
     });
     program
         .command('recipes')
         .description('List all crafting recipes')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/crafting/recipes');
         if (!res.ok)
             handleError(res);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
         formatRecipesLines(res.data).forEach((line) => console.log(line));
     });
 }

package/dist/commands/gather.js

@@ -4,11 +4,16 @@ export function registerGatherCommands(program) {
     program
         .command('gather')
         .description('Harvest resources at current tile')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/actions/gather', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         console.log(formatGatherResultLine(d));
     });
 }

package/dist/commands/guide.js

@@ -125,6 +125,7 @@ const SURVIVAL = `--- Resource & Survival ---
   Inactivity:        8+ hours idle = 10% resource drain/hour (floor: 100g/50f)
   Territory upkeep:  5 food/hr per territory
   Claim cost:        standard 50g+20w+10s+15f (first claim can include onboarding discount) | Max 10 territories
+  Planning tools:    clawcity cost <target> | clawcity afford <target> | clawcity territories
 `;
 const AVATAR = `--- Avatar ---
   Every agent has a unique color derived from their name (body, claw, eye).

package/dist/commands/install.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import inquirer from 'inquirer';
+import { getRequestTimeoutMs } from '../lib/api.js';
 const SKILLS = {
     clawcity: {
         name: 'clawcity',
@@ -50,6 +51,9 @@ export async function installSkill(skillName, options) {
     }
     // Register the agent
     const spinner = ora('Registering your agent...').start();
+    const timeoutMs = getRequestTimeoutMs();
+    const controller = timeoutMs > 0 ? new AbortController() : null;
+    const timeoutHandle = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
     try {
         const response = await fetch(skill.apiUrl, {
             method: 'POST',
@@ -57,6 +61,7 @@ export async function installSkill(skillName, options) {
                 'Content-Type': 'application/json',
             },
             body: JSON.stringify({ name: agentName }),
+            signal: controller?.signal,
         });
         const data = await response.json();
         if (!data.success || !data.data) {
@@ -135,9 +140,19 @@ export async function installSkill(skillName, options) {
         console.log(chalk.cyan('  Heartbeat:   https://clawcity.app/heartbeat.md\n'));
     }
     catch (error) {
+        if (error instanceof Error && error.name === 'AbortError' && timeoutMs > 0) {
+            spinner.fail(chalk.red('Registration timed out'));
+            console.log(chalk.red(`\nError: request timed out after ${Math.ceil(timeoutMs / 1000)}s`));
+            process.exit(124);
+        }
         spinner.fail(chalk.red('Failed to connect to server'));
         console.log(chalk.red(`\nError: ${error instanceof Error ? error.message : 'Unknown error'}`));
         console.log(chalk.gray('\nPlease check your internet connection and try again.'));
         process.exit(1);
     }
+    finally {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
 }

package/dist/commands/move.js

@@ -1,5 +1,5 @@
 import { api, handleError } from '../lib/api.js';
-async function runMoveTo(target, maxSteps) {
+async function runMoveTo(target, maxSteps, asJson) {
     const body = { max_steps: parseInt(maxSteps, 10) };
     // Coordinates support: "350,265" or "350 265"
     const coordMatch = target.match(/^(\d+)[,\s]+(\d+)$/);
@@ -14,6 +14,10 @@ async function runMoveTo(target, maxSteps) {
     if (!res.ok)
         handleError(res);
     const d = res.data;
+    if (asJson) {
+        console.log(JSON.stringify(d, null, 2));
+        return;
+    }
     if (d.error || d.success === false) {
         console.error(`Error: ${d.error || 'Move failed'}`);
         process.exit(1);
@@ -30,21 +34,24 @@ export function registerMoveCommands(program) {
         .command('move <target>')
         .description('Pathfind to terrain type (forest, mountain, ...) or coordinates (x,y)')
         .option('-s, --max-steps <n>', 'Max steps (default 60, max 300)', '60')
+        .option('--json', 'Print raw JSON response')
         .action(async (target, opts) => {
-        await runMoveTo(target, opts.maxSteps);
+        await runMoveTo(target, opts.maxSteps, opts.json);
     });
     // Compatibility alias for auto-mode command drift.
     program
         .command('move-to <target>')
         .description('Alias for "move" (pathfind to terrain or coordinates)')
         .option('-s, --max-steps <n>', 'Max steps (default 60, max 300)', '60')
+        .option('--json', 'Print raw JSON response')
         .action(async (target, opts) => {
-        await runMoveTo(target, opts.maxSteps);
+        await runMoveTo(target, opts.maxSteps, opts.json);
     });
     program
         .command('step <direction>')
         .description('Move one tile: north | south | east | west')
-        .action(async (direction) => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (direction, opts) => {
         const normalized = direction.toLowerCase();
         if (!['north', 'south', 'east', 'west'].includes(normalized)) {
             console.error('Error: direction must be one of north|south|east|west');
@@ -57,6 +64,10 @@ export function registerMoveCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const pos = d.position;
         const terrain = d.terrain ?? 'unknown';
         const x = pos?.x ?? '?';

package/dist/commands/planning.d.ts

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

package/dist/commands/planning.js

@@ -0,0 +1,415 @@
+import { api, handleError } from '../lib/api.js';
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asRecordArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => Boolean(asRecord(entry)))
+        : [];
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function asBoolean(value) {
+    return value === true;
+}
+function parseTarget(rawTarget) {
+    return rawTarget.trim().toLowerCase();
+}
+function formatResourceCost(cost) {
+    const parts = [];
+    const gold = asNumber(cost.gold);
+    const wood = asNumber(cost.wood);
+    const food = asNumber(cost.food);
+    const stone = asNumber(cost.stone);
+    const foodClaimCost = asNumber(cost.food_claim_cost);
+    const staminaCost = asNumber(cost.stamina_cost);
+    const foodTotal = asNumber(cost.food_total);
+    if (gold !== null && gold > 0)
+        parts.push(`${gold} gold`);
+    if (wood !== null && wood > 0)
+        parts.push(`${wood} wood`);
+    if (stone !== null && stone > 0)
+        parts.push(`${stone} stone`);
+    if (food !== null && food > 0)
+        parts.push(`${food} food`);
+    if (foodClaimCost !== null)
+        parts.push(`${foodClaimCost} food (claim cost)`);
+    if (staminaCost !== null)
+        parts.push(`${staminaCost} food (stamina cost)`);
+    if (foodTotal !== null)
+        parts.push(`${foodTotal} food (total)`);
+    return parts.length > 0 ? parts.join(', ') : 'no resource cost';
+}
+function getInventory(stats) {
+    return {
+        gold: asNumber(stats.gold) || 0,
+        wood: asNumber(stats.wood) || 0,
+        food: asNumber(stats.food) || 0,
+        stone: asNumber(stats.stone) || 0,
+    };
+}
+function buildRequirements(inventory, cost) {
+    const toRequirement = (need, have) => ({
+        need,
+        have,
+        missing: Math.max(0, need - have),
+    });
+    return {
+        gold: toRequirement(asNumber(cost.gold) || 0, inventory.gold),
+        wood: toRequirement(asNumber(cost.wood) || 0, inventory.wood),
+        food: toRequirement(asNumber(cost.food) || 0, inventory.food),
+        stone: toRequirement(asNumber(cost.stone) || 0, inventory.stone),
+    };
+}
+function missingRequirementLines(requirements) {
+    return Object.entries(requirements)
+        .filter(([, requirement]) => requirement.missing > 0)
+        .map(([resource, requirement]) => (`${resource} +${requirement.missing} (need ${requirement.need}, have ${requirement.have})`));
+}
+function printReasons(reasons) {
+    if (!Array.isArray(reasons))
+        return;
+    const parsedReasons = reasons.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    if (parsedReasons.length === 0)
+        return;
+    console.log(`Blocked by: ${parsedReasons.join(', ')}`);
+}
+export function registerPlanningCommands(program) {
+    program
+        .command('cost <target>')
+        .description('Show costs for claim, upgrade, buildings, and craft/shop items')
+        .option('--json', 'Print raw JSON response')
+        .action(async (target, opts) => {
+        const normalizedTarget = parseTarget(target);
+        const recipesRes = await api('/api/crafting/recipes', { profile: 'none' });
+        if (!recipesRes.ok)
+            handleError(recipesRes);
+        const data = recipesRes.data;
+        const info = asRecord(data.info) || {};
+        const costs = asRecord(info.costs) || {};
+        const claimCost = asRecord(costs.claim);
+        const upgradeCost = asRecord(costs.upgrade);
+        const buildingCosts = asRecord(costs.buildings) || {};
+        const craftable = asRecordArray(data.craftable);
+        const shop = asRecordArray(data.shop);
+        if (normalizedTarget === 'claim' || normalizedTarget === 'territory') {
+            if (!claimCost) {
+                console.error('Error: claim cost metadata unavailable');
+                process.exit(1);
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(claimCost, null, 2));
+                return;
+            }
+            const baseCost = asRecord(claimCost.base_cost) || {};
+            const discounts = asRecord(claimCost.discounts) || {};
+            console.log(`Claim cost (base): ${formatResourceCost({
+                gold: baseCost.gold,
+                wood: baseCost.wood,
+                stone: baseCost.stone,
+                food_claim_cost: baseCost.food_claim_cost,
+                stamina_cost: baseCost.stamina_cost,
+                food_total: baseCost.food_total,
+            })}`);
+            const firstClaimDiscount = asNumber(discounts.first_claim_percent);
+            const deedDiscount = asNumber(discounts.territory_deed_percent);
+            console.log(`Discounts: first claim ${firstClaimDiscount ?? 0}%, territory deed ${deedDiscount ?? 0}%`);
+            const note = asString(discounts.first_claim_note);
+            if (note) {
+                console.log(`Note: ${note}`);
+            }
+            return;
+        }
+        if (normalizedTarget === 'upgrade' || normalizedTarget.startsWith('upgrade')) {
+            const levels = asRecordArray(upgradeCost?.levels);
+            if (levels.length === 0) {
+                console.error('Error: upgrade cost metadata unavailable');
+                process.exit(1);
+            }
+            let selectedLevels = levels;
+            const levelMatch = normalizedTarget.match(/^upgrade[:_-]?(\d+)$/);
+            if (levelMatch) {
+                const level = Number(levelMatch[1]);
+                selectedLevels = levels.filter((entry) => asNumber(entry.level) === level);
+                if (selectedLevels.length === 0) {
+                    console.error(`Error: Unknown upgrade level ${level}`);
+                    process.exit(1);
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    max_level: asNumber(upgradeCost?.max_level),
+                    levels: selectedLevels,
+                }, null, 2));
+                return;
+            }
+            for (const level of selectedLevels) {
+                const levelNumber = asNumber(level.level) || '?';
+                const levelCost = asRecord(level.cost) || {};
+                const bonusPercent = asNumber(level.territory_gather_bonus_percent);
+                console.log(`Upgrade Lv${levelNumber}: ${formatResourceCost(levelCost)}${bonusPercent !== null ? ` | bonus +${bonusPercent}%` : ''}`);
+            }
+            return;
+        }
+        const building = asRecord(buildingCosts[normalizedTarget]);
+        if (building) {
+            if (opts.json) {
+                console.log(JSON.stringify(building, null, 2));
+                return;
+            }
+            const name = asString(building.name) || normalizedTarget;
+            const buildCost = asRecord(building.build_cost) || {};
+            const upkeep = asRecord(building.hourly_upkeep) || {};
+            console.log(`${name}: build ${formatResourceCost(buildCost)} | upkeep ${formatResourceCost(upkeep)}/hour`);
+            const effect = asString(building.effect_description);
+            if (effect) {
+                console.log(`Effect: ${effect}`);
+            }
+            return;
+        }
+        const craftItem = craftable.find((entry) => asString(entry.id)?.toLowerCase() === normalizedTarget);
+        if (craftItem) {
+            const recipe = asRecord(craftItem.recipe) || {};
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    type: 'craft',
+                    id: asString(craftItem.id),
+                    name: asString(craftItem.name),
+                    recipe,
+                    requires_workshop: craftItem.requires_workshop === true,
+                }, null, 2));
+                return;
+            }
+            console.log(`${asString(craftItem.name) || normalizedTarget} (${normalizedTarget}) craft cost: ${formatResourceCost(recipe)}`);
+            if (craftItem.requires_workshop === true) {
+                console.log('Requires workshop: yes');
+            }
+            return;
+        }
+        const shopItem = shop.find((entry) => asString(entry.id)?.toLowerCase() === normalizedTarget);
+        if (shopItem) {
+            const price = asNumber(shopItem.price);
+            const payload = {
+                gold: price || 0,
+            };
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    type: 'shop',
+                    id: asString(shopItem.id),
+                    name: asString(shopItem.name),
+                    cost: payload,
+                }, null, 2));
+                return;
+            }
+            console.log(`${asString(shopItem.name) || normalizedTarget} (${normalizedTarget}) shop cost: ${formatResourceCost(payload)}`);
+            return;
+        }
+        console.error(`Error: Unknown target "${target}". Use claim, upgrade, building type, or item_id.`);
+        process.exit(1);
+    });
+    program
+        .command('afford <target>')
+        .description('Check if you can currently afford an action/item and what is missing')
+        .option('--json', 'Print raw JSON response')
+        .action(async (target, opts) => {
+        const normalizedTarget = parseTarget(target);
+        const [statsRes, recipesRes] = await Promise.all([
+            api('/api/agents/me/stats'),
+            api('/api/crafting/recipes', { profile: 'none' }),
+        ]);
+        if (!statsRes.ok)
+            handleError(statsRes);
+        if (!recipesRes.ok)
+            handleError(recipesRes);
+        const stats = statsRes.data;
+        const inventory = getInventory(stats);
+        const eligibility = asRecord(stats.action_eligibility) || {};
+        const recipesData = recipesRes.data;
+        const craftable = asRecordArray(recipesData.craftable);
+        const shop = asRecordArray(recipesData.shop);
+        if (normalizedTarget === 'claim' || normalizedTarget === 'territory') {
+            const claim = asRecord(eligibility.claim) || {};
+            const result = {
+                target: 'claim',
+                can_execute: asBoolean(claim.can_execute),
+                can_afford: asBoolean(claim.can_afford),
+                affordable_now: asBoolean(claim.can_execute) && asBoolean(claim.can_afford),
+                reasons: Array.isArray(claim.reasons) ? claim.reasons : [],
+                effective_cost: asRecord(claim.effective_cost) || {},
+                missing_resources: Array.isArray(claim.missing_resources) ? claim.missing_resources : [],
+                requirements: asRecord(claim.requirements) || {},
+                current_tile: asRecord(stats.current_tile) || {},
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Claim here: ${result.affordable_now ? 'YES' : 'NO'}`);
+            console.log(`Cost: ${formatResourceCost(result.effective_cost)}`);
+            if (result.missing_resources.length > 0) {
+                console.log(`Missing: ${result.missing_resources.join('; ')}`);
+            }
+            printReasons(result.reasons);
+            return;
+        }
+        if (normalizedTarget === 'upgrade') {
+            const upgrade = asRecord(eligibility.upgrade) || {};
+            const result = {
+                target: 'upgrade',
+                can_execute: asBoolean(upgrade.can_execute),
+                can_afford: asBoolean(upgrade.can_afford),
+                affordable_now: asBoolean(upgrade.can_execute) && asBoolean(upgrade.can_afford),
+                reasons: Array.isArray(upgrade.reasons) ? upgrade.reasons : [],
+                current_level: asNumber(upgrade.current_level),
+                next_level: asNumber(upgrade.next_level),
+                cost: asRecord(upgrade.cost) || {},
+                missing_resources: Array.isArray(upgrade.missing_resources) ? upgrade.missing_resources : [],
+                requirements: asRecord(upgrade.requirements) || {},
+                current_tile: asRecord(stats.current_tile) || {},
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Upgrade here: ${result.affordable_now ? 'YES' : 'NO'}`);
+            if (result.next_level !== null) {
+                console.log(`Next level: Lv${result.next_level}`);
+                console.log(`Cost: ${formatResourceCost(result.cost)}`);
+            }
+            else {
+                console.log('Cost: unavailable (already max level or not upgradeable)');
+            }
+            if (result.missing_resources.length > 0) {
+                console.log(`Missing: ${result.missing_resources.join('; ')}`);
+            }
+            printReasons(result.reasons);
+            return;
+        }
+        const build = asRecord(eligibility.build) || {};
+        const buildOptions = asRecord(build.options) || {};
+        const buildOption = asRecord(buildOptions[normalizedTarget]);
+        if (buildOption) {
+            const canExecute = asBoolean(build.can_execute);
+            const canAffordTarget = asBoolean(buildOption.can_afford);
+            const result = {
+                target: normalizedTarget,
+                can_execute: canExecute,
+                can_afford: canAffordTarget,
+                affordable_now: canExecute && canAffordTarget,
+                reasons: Array.isArray(build.reasons) ? build.reasons : [],
+                cost: asRecord(buildOption.cost) || {},
+                missing_resources: Array.isArray(buildOption.missing_resources) ? buildOption.missing_resources : [],
+                requirements: asRecord(buildOption.requirements) || {},
+                current_tile: asRecord(stats.current_tile) || {},
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Build ${normalizedTarget}: ${result.affordable_now ? 'YES' : 'NO'}`);
+            console.log(`Cost: ${formatResourceCost(result.cost)}`);
+            if (result.missing_resources.length > 0) {
+                console.log(`Missing: ${result.missing_resources.join('; ')}`);
+            }
+            printReasons(result.reasons);
+            return;
+        }
+        const craftItem = craftable.find((entry) => asString(entry.id)?.toLowerCase() === normalizedTarget);
+        if (craftItem) {
+            const recipe = asRecord(craftItem.recipe) || {};
+            const requirements = buildRequirements(inventory, recipe);
+            const missing = missingRequirementLines(requirements);
+            const requiresWorkshop = craftItem.requires_workshop === true;
+            const result = {
+                target: normalizedTarget,
+                type: 'craft',
+                affordable_now: missing.length === 0,
+                requires_workshop: requiresWorkshop,
+                cost: recipe,
+                missing_resources: missing,
+                requirements,
+                inventory,
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Craft ${normalizedTarget}: ${result.affordable_now ? 'YES' : 'NO'}`);
+            console.log(`Cost: ${formatResourceCost(recipe)}`);
+            if (requiresWorkshop) {
+                console.log('Requires workshop: yes');
+            }
+            if (missing.length > 0) {
+                console.log(`Missing: ${missing.join('; ')}`);
+            }
+            return;
+        }
+        const shopItem = shop.find((entry) => asString(entry.id)?.toLowerCase() === normalizedTarget);
+        if (shopItem) {
+            const price = asNumber(shopItem.price) || 0;
+            const cost = { gold: price };
+            const requirements = buildRequirements(inventory, cost);
+            const missing = missingRequirementLines(requirements);
+            const result = {
+                target: normalizedTarget,
+                type: 'shop',
+                affordable_now: missing.length === 0,
+                cost,
+                missing_resources: missing,
+                requirements,
+                inventory,
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Buy ${normalizedTarget}: ${result.affordable_now ? 'YES' : 'NO'}`);
+            console.log(`Cost: ${formatResourceCost(cost)}`);
+            if (missing.length > 0) {
+                console.log(`Missing: ${missing.join('; ')}`);
+            }
+            return;
+        }
+        console.error(`Error: Unknown target "${target}". Use claim, upgrade, building type, or item_id.`);
+        process.exit(1);
+    });
+    program
+        .command('territories')
+        .description('List your owned territories with upgrade/building details')
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
+        const res = await api('/api/agents/me', {
+            query: { fields: 'territories,position' },
+        });
+        if (!res.ok)
+            handleError(res);
+        const data = res.data;
+        const territories = asRecordArray(data.territories);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                count: territories.length,
+                territories,
+            }, null, 2));
+            return;
+        }
+        if (territories.length === 0) {
+            console.log('No territories owned.');
+            return;
+        }
+        for (const territory of territories) {
+            const x = asNumber(territory.x);
+            const y = asNumber(territory.y);
+            const terrain = asString(territory.terrain) || 'unknown';
+            const level = asNumber(territory.upgrade_level) || 1;
+            const buildingType = asString(territory.building_type);
+            console.log(`(${x ?? '?'},${y ?? '?'}) ${terrain} | Lv${level}${buildingType ? ` | building:${buildingType}` : ''}`);
+        }
+        console.log(`Total territories: ${territories.length}`);
+    });
+}

package/dist/commands/stats.js

@@ -37,7 +37,7 @@ export function registerStatsCommands(program) {
     program
         .command('status')
         .description('Full agent status with all details')
-        .option('-f, --fields <fields>', 'Comma-separated fields: inventory,position,wealth,items,buildings,nearby,trades,announcements')
+        .option('-f, --fields <fields>', 'Comma-separated fields: inventory,position,wealth,items,buildings,territories,nearby,trades,announcements,avatar')
         .action(async (opts) => {
         const path = opts.fields
             ? `/api/agents/me?fields=${opts.fields}`

package/dist/commands/territory.js

@@ -3,11 +3,16 @@ export function registerTerritoryCommands(program) {
     const claim = program
         .command('claim')
         .description('Claim current tile (standard: 50g+20w+10s+15f; first claim may receive onboarding discount)')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/actions/claim', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const inv = d.inventory;
         const count = d.territory_count ?? '?';
         console.log(`Claimed tile | Territories: ${count}${inv ? ` | ${fmtResources(inv)}` : ''}`);
@@ -45,11 +50,16 @@ export function registerTerritoryCommands(program) {
     program
         .command('upgrade')
         .description('Upgrade current territory (Lv2: 50w+25s, Lv3: 100w+50s)')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/actions/upgrade', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const level = d.level ?? d.new_level ?? '?';
         const inv = d.inventory;
         console.log(`Upgraded to level ${level}${inv ? ` | ${fmtResources(inv)}` : ''}`);
@@ -57,21 +67,31 @@ export function registerTerritoryCommands(program) {
     program
         .command('build <type>')
         .description('Build on owned tile (storage, workshop, fortification)')
-        .action(async (type) => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (type, opts) => {
         const res = await api('/api/actions/build', { method: 'POST', body: { building_type: type } });
         if (!res.ok)
             handleError(res);
         const d = res.data;
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+        }
         const inv = d.inventory;
         console.log(`Built ${type}${inv ? ` | ${fmtResources(inv)}` : ''}`);
     });
     program
         .command('demolish')
         .description('Remove building on current tile')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/actions/demolish', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
         console.log('Building demolished');
     });
 }

package/dist/index.js

@@ -20,8 +20,18 @@ import { registerApiCommands } from './commands/api.js';
 import { registerProfileCommands } from './commands/profile.js';
 import { registerFeedbackCommands } from './commands/feedback.js';
 import { registerOracleCommands } from './commands/oracle.js';
+import { registerPlanningCommands } from './commands/planning.js';
+import { setRequestTimeoutMs } from './lib/api.js';
 const program = new Command();
 let cliVersion = '0.0.0';
+function parseTimeoutMs(rawValue) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        console.error('Error: --timeout must be a non-negative number of seconds.');
+        process.exit(1);
+    }
+    return Math.round(parsed * 1000);
+}
 try {
     const pkgPath = new URL('../package.json', import.meta.url);
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
@@ -34,6 +44,14 @@ program
     .name('clawcity')
     .description('CLI tool for ClawCity - the AI agent MMO')
     .version(cliVersion);
+program
+    .option('--timeout <seconds>', 'HTTP timeout in seconds for API requests (0 disables timeout)');
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals();
+    if (opts.timeout !== undefined) {
+        setRequestTimeoutMs(parseTimeoutMs(opts.timeout));
+    }
+});
 program
     .command('install <skill>')
     .description('Install a skill for your AI agent')
@@ -59,4 +77,5 @@ registerProfileCommands(program);
 registerFeedbackCommands(program);
 registerOracleCommands(program);
 registerApiCommands(program);
+registerPlanningCommands(program);
 program.parse();

package/dist/lib/api.d.ts

@@ -15,6 +15,7 @@ interface ApiOptions {
     profile?: AuthProfile;
     query?: Record<string, string | number | boolean | null | undefined>;
     headers?: Record<string, string>;
+    timeoutMs?: number;
 }
 interface RawRequestResponse {
     ok: boolean;
@@ -27,6 +28,8 @@ interface ApiResponse {
     status: number;
     data: Record<string, unknown>;
 }
+export declare function setRequestTimeoutMs(timeoutMs: number): void;
+export declare function getRequestTimeoutMs(): number;
 export declare function requestApi(path: string, opts?: ApiOptions): Promise<RawRequestResponse>;
 export declare function api(path: string, opts?: ApiOptions): Promise<ApiResponse>;
 /** Print error from API response and exit */

package/dist/lib/api.js

@@ -10,6 +10,34 @@ const BASE_URL = process.env.CLAWCITY_URL || 'https://www.clawcity.app';
 const API_KEY = process.env.CLAWCITY_API_KEY || '';
 const SESSION_COOKIE = process.env.CLAWCITY_SESSION_COOKIE || '';
 const CRON_SECRET = process.env.CLAWCITY_CRON_SECRET || '';
+const DEFAULT_TIMEOUT_SECONDS = (() => {
+    const raw = process.env.CLAWCITY_TIMEOUT;
+    if (!raw)
+        return 60;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 60;
+    return parsed;
+})();
+const TIMEOUT_EXIT_CODE = 124;
+let runtimeTimeoutMs = Math.round(DEFAULT_TIMEOUT_SECONDS * 1000);
+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 setRequestTimeoutMs(timeoutMs) {
+    runtimeTimeoutMs = Math.max(0, Math.round(timeoutMs));
+}
+export function getRequestTimeoutMs() {
+    return runtimeTimeoutMs;
+}
 function ensureCredentialOrExit(profile, headers) {
     const hasAuthHeader = Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
     const hasCookieHeader = Object.keys(headers).some((key) => key.toLowerCase() === 'cookie');
@@ -59,6 +87,8 @@ export async function requestApi(path, opts = {}) {
     const method = opts.method || 'GET';
     const profile = normalizeProfile(opts);
     const headers = { ...(opts.headers || {}) };
+    const timeoutMs = opts.timeoutMs !== undefined ? Math.max(0, Math.round(opts.timeoutMs)) : runtimeTimeoutMs;
+    const isMutation = method !== 'GET';
     if (profile === 'agent' && !headers.Authorization && API_KEY) {
         headers.Authorization = `Bearer ${API_KEY}`;
     }
@@ -75,11 +105,16 @@ export async function requestApi(path, opts = {}) {
     }
     const url = toUrl(path);
     appendQuery(url, opts.query);
+    const controller = timeoutMs > 0 ? new AbortController() : null;
+    const timeoutHandle = controller
+        ? setTimeout(() => controller.abort(), timeoutMs)
+        : null;
     try {
         const res = await fetch(url, {
             method,
             headers,
             body: bodyText,
+            signal: controller?.signal,
         });
         const text = await res.text();
         let json;
@@ -100,9 +135,23 @@ export async function requestApi(path, opts = {}) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        const isAbort = err instanceof Error && err.name === 'AbortError';
+        if (isAbort && timeoutMs > 0) {
+            console.error(`Error: Request timed out after ${Math.ceil(timeoutMs / 1000)}s (${method} ${url.pathname})`);
+            if (isMutation) {
+                console.error('Outcome may be uncertain for mutating requests. Run clawcity stats before retrying.');
+            }
+            process.exit(TIMEOUT_EXIT_CODE);
+        }
         console.error(`Error: ${msg}`);
         process.exit(1);
     }
+    finally {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    throw new Error('Unreachable');
 }
 export async function api(path, opts = {}) {
     const res = await requestApi(path, opts);
@@ -132,7 +181,36 @@ export async function api(path, opts = {}) {
 /** Print error from API response and exit */
 export function handleError(res) {
     const msg = res.data.error || res.data.message || `HTTP ${res.status}`;
-    console.error(`Error: ${String(msg)}`);
+    const code = asString(res.data.code);
+    const hint = asString(res.data.hint);
+    const retryAfterSeconds = asNumber(res.data.retry_after_seconds);
+    const details = asRecord(res.data.details);
+    console.error(`Error${code ? ` [${code}]` : ''}: ${String(msg)}`);
+    if (details) {
+        const requirements = asRecord(details.requirements);
+        if (requirements) {
+            const missing = Object.entries(requirements)
+                .map(([resource, value]) => {
+                const requirement = asRecord(value);
+                const need = asNumber(requirement?.need);
+                const have = asNumber(requirement?.have);
+                const miss = asNumber(requirement?.missing);
+                if (need === null || have === null || miss === null || miss <= 0)
+                    return null;
+                return `${resource} +${miss} (need ${need}, have ${have})`;
+            })
+                .filter((entry) => Boolean(entry));
+            if (missing.length > 0) {
+                console.error(`Missing: ${missing.join('; ')}`);
+            }
+        }
+    }
+    if (retryAfterSeconds !== null) {
+        console.error(`Retry after: ${retryAfterSeconds}s`);
+    }
+    if (hint) {
+        console.error(`Hint: ${hint}`);
+    }
     process.exit(1);
 }
 /** Format resources compactly: G:100 W:20 F:50 S:30 */

package/package.json

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