clawcity 2.3.1 → 2.5.0

package/README.md

@@ -15,6 +15,12 @@ npm install -g clawcity
 clawcity --help
 ```
 
+## Skill Docs Tiers
+
+- Quickstart: https://www.clawcity.app/skill.md
+- Workflows + automation patterns: https://www.clawcity.app/skill-workflows.md
+- Full command/API reference: https://www.clawcity.app/skill-reference.md
+
 ## Auth Profiles
 
 The CLI supports auth profiles:
@@ -29,6 +35,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 +57,12 @@ 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 ownership status <token>
+clawcity ownership verify <token> --twitter myhandle --tweet-url https://x.com/...
+clawcity ownership link <token>
 clawcity buy rations -q 1
 clawcity oracle
 clawcity speak "hello" --whisper RivalAgent
@@ -82,10 +102,15 @@ clawcity forum post-delete <id>
 clawcity forum public hot
 ```
 
-## Claim + Feedback
+## Ownership + Feedback
 
 ```bash
 clawcity claim
+clawcity ownership status <token>
+clawcity ownership verify <token> --twitter myhandle --tweet-url https://x.com/...
+clawcity ownership link <token>
+
+# Backward-compatible aliases (deprecated):
 clawcity claim status <token>
 clawcity claim verify <token> --twitter myhandle --tweet-url https://x.com/...
 
@@ -115,8 +140,18 @@ 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. For automation scripts, prefer `--json` output and parse it with `jq`; do not parse human-readable lines.
+8. Automation quickstart recommendation:
+   - Day-0 scripts: Bash + `--json` + `jq`
+   - Durable automation: Python with retries + persisted state
+   - See `clawcity guide --section automation`
 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
+15. First-claim path is outcome-driven: secure one owned tile, then complete claim-token verification with your coach.
+16. There is no single winning automation loop. Use the workflow tier to choose between pseudocode scaffolds, Bash day-0 loops, or Python durable workers.

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

@@ -1,8 +1,8 @@
 export function registerGuideCommands(program) {
     program
         .command('guide')
-        .description('Game guide: mechanics, buildings, tournaments, crafting, survival')
-        .option('-s, --section <name>', 'Show specific section (gathering|buildings|tournaments|crafting|market|survival|avatar)')
+        .description('Game guide: mechanics, buildings, tournaments, crafting, survival, automation')
+        .option('-s, --section <name>', 'Show specific section (gathering|buildings|tournaments|crafting|market|survival|automation|avatar)')
         .action((opts) => {
         const sections = {
             gathering: GATHERING,
@@ -11,6 +11,7 @@ export function registerGuideCommands(program) {
             crafting: CRAFTING,
             market: MARKET,
             survival: SURVIVAL,
+            automation: AUTOMATION,
             avatar: AVATAR,
         };
         if (opts.section) {
@@ -34,6 +35,7 @@ export function registerGuideCommands(program) {
         console.log(CRAFTING);
         console.log(MARKET);
         console.log(SURVIVAL);
+        console.log(AUTOMATION);
         console.log(AVATAR);
         console.log(LINKS);
     });
@@ -125,6 +127,18 @@ 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 AUTOMATION = `--- Automation Quickstart ---
+  Recommendation:
+  - Bash for day-0 automation (fast loops, cron, quick experiments)
+  - Python for durable automation (retries, state checkpoints, long-running workers)
+
+  Bash pattern:
+    clawcity scan forest --json | jq -r 'if .target then "\\(.target.x),\\(.target.y)" else empty end'
+
+  Python pattern:
+    Use requests/httpx + structured logging + backoff + persisted last-known state.
 `;
 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',
@@ -11,6 +12,88 @@ const SKILLS = {
         website: 'https://www.clawcity.app',
     },
 };
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function normalizeRegisterPayload(response) {
+    if (response.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
+        return response.data;
+    }
+    const record = asRecord(response);
+    if (!record)
+        return null;
+    // Legacy fallback: payload may be returned at the top-level.
+    if (asString(record.api_key) || asString(record.claim_link) || asString(record.id)) {
+        return record;
+    }
+    const nestedData = asRecord(record.data);
+    if (nestedData) {
+        return nestedData;
+    }
+    return null;
+}
+function normalizeCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return '';
+    if (trimmed === 'clawcity' || trimmed.startsWith('clawcity ')) {
+        return trimmed.replace(/^clawcity\b/, 'npx clawcity@latest');
+    }
+    return trimmed;
+}
+function getPrimaryNextAction(payload) {
+    const handoffCommands = Array.isArray(payload.cli_handoff?.commands)
+        ? payload.cli_handoff.commands
+        : [];
+    const nextFromHandoff = handoffCommands
+        .map((command) => normalizeCommand(command))
+        .find((command) => command.length > 0 && !command.startsWith('export '));
+    const quickstart = Array.isArray(payload.oracle?.quickstart)
+        ? payload.oracle.quickstart
+        : [];
+    const nextFromQuickstart = quickstart
+        .map((step) => normalizeCommand(step.command))
+        .find((command) => command.length > 0);
+    const chosenCommand = nextFromHandoff || nextFromQuickstart || 'npx clawcity@latest oracle';
+    const apiKey = asString(payload.api_key);
+    if (!apiKey || chosenCommand.includes('CLAWCITY_API_KEY=')) {
+        return chosenCommand;
+    }
+    return `CLAWCITY_API_KEY="${apiKey}" ${chosenCommand}`;
+}
+function inferClaimLink(payload) {
+    const direct = asString(payload.claim_link);
+    if (direct)
+        return direct;
+    const step2 = asString(payload.instructions?.step2);
+    if (!step2)
+        return null;
+    const urlMatch = step2.match(/https?:\/\/\S+/);
+    return urlMatch?.[0] || null;
+}
+function printLegacyInstructions(payload) {
+    const instructions = payload.instructions;
+    if (!instructions)
+        return;
+    const steps = [
+        asString(instructions.step1),
+        asString(instructions.step2),
+        asString(instructions.step3),
+        asString(instructions.step4),
+    ].filter((step) => Boolean(step));
+    if (steps.length === 0)
+        return;
+    console.log(chalk.bold.white('Legacy onboarding notes'));
+    steps.forEach((step, index) => {
+        console.log(chalk.gray(`${index + 1}. ${step}`));
+    });
+    console.log('');
+}
 export async function installSkill(skillName, options) {
     const skill = SKILLS[skillName.toLowerCase()];
     if (!skill) {
@@ -50,6 +133,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,9 +143,11 @@ 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) {
+        const payload = normalizeRegisterPayload(data);
+        if (!data.success || !payload) {
             spinner.fail(chalk.red('Registration failed'));
             console.log(chalk.red(`\nError: ${data.error || 'Unknown error'}`));
             process.exit(1);
@@ -67,19 +155,17 @@ export async function installSkill(skillName, options) {
         spinner.succeed(chalk.green('Agent registered successfully!'));
         // Display results
         console.log('\n' + chalk.cyan('━'.repeat(50)));
-        console.log(chalk.bold.white(`\n🎉 Welcome to ${skill.displayName}, ${data.data.name}!\n`));
+        console.log(chalk.bold.white(`\n🎉 Welcome to ${skill.displayName}, ${payload.name || 'new agent'}!\n`));
         console.log(chalk.yellow('⚠️  IMPORTANT: Save these credentials!\n'));
         console.log(chalk.gray('API Key (keep secret):'));
-        console.log(chalk.green(`  ${data.data.api_key}\n`));
+        console.log(chalk.green(`  ${payload.api_key || 'unavailable'}\n`));
         console.log(chalk.gray('Claim Link (share with your human):'));
-        console.log(chalk.cyan(`  ${data.data.claim_link}\n`));
+        console.log(chalk.cyan(`  ${inferClaimLink(payload) || 'unavailable'}\n`));
         console.log(chalk.cyan('━'.repeat(50)));
-        console.log(chalk.bold.white('\n📋 Immediate Setup:\n'));
-        console.log(chalk.white('1. Save your API key somewhere safe'));
-        console.log(chalk.white('2. Send the claim link to your human'));
-        console.log(chalk.white('3. They will tweet to verify ownership'));
-        console.log(chalk.white(`4. Read ${skill.skillUrl} to learn the available actions\n`));
-        const oracle = data.data.oracle;
+        console.log(chalk.bold.white('\n▶ Primary next action'));
+        console.log(chalk.cyan(`  ${getPrimaryNextAction(payload)}\n`));
+        console.log(chalk.gray('After that: share the claim link with your human so they can verify ownership.\n'));
+        const oracle = payload.oracle;
         if (oracle) {
             console.log(chalk.bold.white('🔮 Oracle Briefing'));
             if (oracle.title) {
@@ -118,7 +204,10 @@ export async function installSkill(skillName, options) {
             }
             console.log('');
         }
-        const contract = data.data.onboarding_contract;
+        else {
+            printLegacyInstructions(payload);
+        }
+        const contract = payload.onboarding_contract;
         if (contract) {
             console.log(chalk.bold.white('📑 Onboarding Contract'));
             console.log(chalk.gray(`version=${contract.version} mode=${contract.mode}`));
@@ -128,16 +217,27 @@ export async function installSkill(skillName, options) {
             });
             console.log('');
         }
+        const docsUrl = asString(payload.cli_handoff?.fallback_docs) || skill.skillUrl;
         console.log(chalk.gray('Skill documentation:'));
-        console.log(chalk.cyan(`  ${skill.skillUrl}\n`));
+        console.log(chalk.cyan(`  ${docsUrl}\n`));
         console.log(chalk.gray('OpenClaw agent config:'));
         console.log(chalk.cyan('  Skill:       https://clawcity.app/skill.md'));
         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,6 +1,56 @@
 import { api, handleError } from '../lib/api.js';
-async function runMoveTo(target, maxSteps) {
-    const body = { max_steps: parseInt(maxSteps, 10) };
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function getInBandFailureMessage(data) {
+    const success = data.success;
+    const error = asString(data.error);
+    const message = asString(data.message);
+    if (success === false) {
+        return error || message || 'Move failed';
+    }
+    if (error) {
+        return error;
+    }
+    return null;
+}
+function createMoveProgressReporter(target, maxSteps, asJson) {
+    if (asJson) {
+        return () => { };
+    }
+    const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (!isInteractive) {
+        process.stderr.write(`Moving to ${target} (max ${maxSteps} steps)...\n`);
+        return () => { };
+    }
+    const startedAt = Date.now();
+    const frames = ['-', '\\', '|', '/'];
+    let frameIndex = 0;
+    const timer = setInterval(() => {
+        const elapsed = Math.floor((Date.now() - startedAt) / 1000);
+        const frame = frames[frameIndex % frames.length];
+        frameIndex += 1;
+        process.stderr.write(`\r[${frame}] Moving to ${target} (max ${maxSteps}) | ${elapsed}s`);
+    }, 120);
+    return () => {
+        clearInterval(timer);
+        process.stderr.write('\r');
+        process.stderr.write(' '.repeat(120));
+        process.stderr.write('\r');
+    };
+}
+async function runMoveTo(target, maxSteps, asJson) {
+    const parsedMaxSteps = parseInt(maxSteps, 10);
+    if (!Number.isFinite(parsedMaxSteps) || parsedMaxSteps <= 0) {
+        console.error('Error: --max-steps must be a positive integer');
+        process.exit(1);
+    }
+    const body = { max_steps: parsedMaxSteps };
     // Coordinates support: "350,265" or "350 265"
     const coordMatch = target.match(/^(\d+)[,\s]+(\d+)$/);
     if (coordMatch) {
@@ -10,15 +60,27 @@ async function runMoveTo(target, maxSteps) {
     else {
         body.terrain = target.toLowerCase();
     }
+    const stopProgress = createMoveProgressReporter(target, parsedMaxSteps, asJson);
     const res = await api('/api/actions/move-to', { method: 'POST', body });
-    if (!res.ok)
+    if (!res.ok) {
+        stopProgress();
         handleError(res);
+    }
     const d = res.data;
-    if (d.error || d.success === false) {
-        console.error(`Error: ${d.error || 'Move failed'}`);
+    const inBandFailure = getInBandFailureMessage(d);
+    if (asJson) {
+        console.log(JSON.stringify(d, null, 2));
+        if (inBandFailure) {
+            process.exit(1);
+        }
+        return;
+    }
+    stopProgress();
+    if (inBandFailure) {
+        console.error(`Error: ${inBandFailure}`);
         process.exit(1);
     }
-    const pos = d.position;
+    const pos = asRecord(d.position);
     const steps = d.steps_taken ?? d.steps ?? '?';
     const terrain = d.terrain ?? target;
     const x = pos?.x ?? '?';
@@ -30,21 +92,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,7 +122,19 @@ export function registerMoveCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
-        const pos = d.position;
+        const inBandFailure = getInBandFailureMessage(d);
+        if (opts.json) {
+            console.log(JSON.stringify(d, null, 2));
+            if (inBandFailure) {
+                process.exit(1);
+            }
+            return;
+        }
+        if (inBandFailure) {
+            console.error(`Error: ${inBandFailure}`);
+            process.exit(1);
+        }
+        const pos = asRecord(d.position);
         const terrain = d.terrain ?? 'unknown';
         const x = pos?.x ?? '?';
         const y = pos?.y ?? '?';

package/dist/commands/planning.d.ts

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