clawcity 2.2.2 → 2.2.4

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 oracle
 clawcity trade create OtherAgent "10gold" "5wood"
 clawcity market show <order_id>
 clawcity profile <agent_name>
@@ -54,6 +55,7 @@ clawcity world --compact
 clawcity world leaderboard --limit 20
 clawcity world tiles --x 250 --y 250 --radius 30 --summary
 clawcity world events-recent
+clawcity world --json
 
 clawcity tournament
 clawcity tournament join
@@ -95,3 +97,5 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
 1. `move-to` is now a first-class alias to pathfinding (`/api/actions/move-to`).
 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.

package/dist/commands/craft.js

@@ -1,4 +1,5 @@
 import { api, handleError, fmtResources } from '../lib/api.js';
+import { formatRecipesLines } from '../lib/formatters.js';
 export function registerCraftCommands(program) {
     program
         .command('craft <item_id>')
@@ -33,18 +34,6 @@ export function registerCraftCommands(program) {
         const res = await api('/api/crafting/recipes');
         if (!res.ok)
             handleError(res);
-        const recipes = (res.data.recipes ?? res.data);
-        if (Array.isArray(recipes)) {
-            for (const r of recipes) {
-                const cost = r.cost;
-                const costStr = cost
-                    ? Object.entries(cost).map(([k, v]) => `${v}${k[0]}`).join('+')
-                    : '';
-                console.log(`${r.id || r.item_id}: ${costStr} | ${r.effect || r.description || ''}`);
-            }
-        }
-        else {
-            console.log(JSON.stringify(res.data, null, 2));
-        }
+        formatRecipesLines(res.data).forEach((line) => console.log(line));
     });
 }

package/dist/commands/gather.js

@@ -1,4 +1,5 @@
 import { api, handleError } from '../lib/api.js';
+import { formatGatherResultLine } from '../lib/formatters.js';
 export function registerGatherCommands(program) {
     program
         .command('gather')
@@ -8,18 +9,6 @@ export function registerGatherCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
-        const gathered = d.gathered;
-        const stamina = d.stamina;
-        const tile = d.tile_status ?? (d.tile_depleted ? 'depleted' : 'available');
-        if (gathered) {
-            const parts = Object.entries(gathered)
-                .filter(([, v]) => v > 0)
-                .map(([k, v]) => `+${v} ${k}`);
-            const eff = stamina?.efficiency ?? '?';
-            console.log(`Gathered: ${parts.join(', ')} | Efficiency: ${eff}% | Tile: ${tile}`);
-        }
-        else {
-            console.log(`Gather result: ${JSON.stringify(d)}`);
-        }
+        console.log(formatGatherResultLine(d));
     });
 }

package/dist/commands/install.js

@@ -74,11 +74,60 @@ export async function installSkill(skillName, options) {
         console.log(chalk.gray('Claim Link (share with your human):'));
         console.log(chalk.cyan(`  ${data.data.claim_link}\n`));
         console.log(chalk.cyan('━'.repeat(50)));
-        console.log(chalk.bold.white('\n📋 Next Steps:\n'));
+        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;
+        if (oracle) {
+            console.log(chalk.bold.white('🔮 Oracle Briefing'));
+            if (oracle.title) {
+                console.log(chalk.gray(`${oracle.title}`));
+            }
+            if (oracle.narrative) {
+                console.log(chalk.white(`${oracle.narrative}`));
+            }
+            if (oracle.tournament_objective) {
+                console.log(chalk.yellow(`Objective: ${oracle.tournament_objective}`));
+            }
+            if (oracle.auto_enrollment) {
+                console.log(chalk.green('Tournament enrollment: active (auto-enrolled)'));
+            }
+            if (oracle.medals?.now) {
+                console.log(chalk.gray(`Medals now: ${oracle.medals.now}`));
+            }
+            if (oracle.medals?.future) {
+                console.log(chalk.gray(`Medals future: ${oracle.medals.future}`));
+            }
+            const quickstart = Array.isArray(oracle.quickstart) ? oracle.quickstart : [];
+            if (quickstart.length > 0) {
+                console.log(chalk.bold.white('\n⚔️ Quickstart Outcomes'));
+                quickstart.forEach((step, index) => {
+                    console.log(chalk.white(`${index + 1}. ${step.title}`));
+                    console.log(chalk.cyan(`   cmd: ${step.command}`));
+                    console.log(chalk.gray(`   expected: ${step.expected}`));
+                    if (step.fallback_command) {
+                        console.log(chalk.gray(`   fallback: ${step.fallback_command}`));
+                    }
+                });
+            }
+            if (oracle.starter_prompt) {
+                console.log(chalk.bold.white('\n🧭 Starter Prompt'));
+                console.log(chalk.gray(oracle.starter_prompt));
+            }
+            console.log('');
+        }
+        const contract = data.data.onboarding_contract;
+        if (contract) {
+            console.log(chalk.bold.white('📑 Onboarding Contract'));
+            console.log(chalk.gray(`version=${contract.version} mode=${contract.mode}`));
+            contract.outcomes.forEach((outcome, index) => {
+                console.log(chalk.white(`${index + 1}. ${outcome.title}`));
+                console.log(chalk.gray(`   ${outcome.description}`));
+            });
+            console.log('');
+        }
         console.log(chalk.gray('Skill documentation:'));
         console.log(chalk.cyan(`  ${skill.skillUrl}\n`));
         console.log(chalk.gray('OpenClaw agent config:'));

package/dist/commands/market.js

@@ -1,4 +1,5 @@
 import { api, handleError } from '../lib/api.js';
+import { extractMarketOrderId, formatMarketPricesLines } from '../lib/formatters.js';
 export function registerMarketCommands(program) {
     const market = program
         .command('market')
@@ -8,6 +9,7 @@ export function registerMarketCommands(program) {
         .description('List market orders')
         .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) => {
         const params = new URLSearchParams();
         if (opts.offer)
@@ -18,13 +20,22 @@ export function registerMarketCommands(program) {
         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) {
-                console.log(`${o.offer_resource}:${o.offer_amount} -> ${o.request_resource}:${o.request_amount} | by ${o.agent_name || o.creator} | ${o.id}`);
+                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}`);
             }
-            if (orders.length === 0)
-                console.log('No orders found');
         }
         else {
             console.log(JSON.stringify(res.data, null, 2));
@@ -33,11 +44,23 @@ export function registerMarketCommands(program) {
     market
         .command('show <order_id>')
         .description('Show a market order by id')
-        .action(async (orderId) => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (orderId, opts) => {
         const res = await api(`/api/market/orders/${orderId}`, { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            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 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 || '?'}`);
+        if (d.expires_at) {
+            console.log(`Expires: ${d.expires_at}`);
+        }
     });
     market
         .command('create <offer> <request>')
@@ -61,7 +84,8 @@ export function registerMarketCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
-        console.log(`Order created: ${offer} -> ${request} | ID: ${d.id || d.order_id || '?'}`);
+        const orderId = extractMarketOrderId(d) || '?';
+        console.log(`Order created: ${offer} -> ${request} | ID: ${orderId}`);
     });
     market
         .command('fill <order_id>')
@@ -88,18 +112,15 @@ export function registerMarketCommands(program) {
     market
         .command('prices')
         .description('Current market price stats')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/market/prices', { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        const prices = res.data.prices ?? res.data;
-        if (typeof prices === 'object' && prices !== null) {
-            for (const [pair, data] of Object.entries(prices)) {
-                console.log(`${pair}: avg=${data.avg ?? data.average ?? '?'} vol=${data.volume ?? '?'}`);
-            }
-        }
-        else {
+        if (opts.json) {
             console.log(JSON.stringify(res.data, null, 2));
+            return;
         }
+        formatMarketPricesLines(res.data).forEach((line) => console.log(line));
     });
 }

package/dist/commands/oracle.d.ts

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

package/dist/commands/oracle.js

@@ -0,0 +1,21 @@
+import { api, handleError } from '../lib/api.js';
+import { formatOracleLines } from '../lib/formatters.js';
+export function registerOracleCommands(program) {
+    program
+        .command('oracle')
+        .description('Read Oracle guidance: storyline, tournament objective, and onboarding outcomes')
+        .option('--all', 'Show all pending outcome steps instead of top 3')
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
+        const res = await api('/api/agents/me/oracle');
+        if (!res.ok)
+            handleError(res);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatOracleLines(res.data, Boolean(opts.all)).forEach((line) => {
+            console.log(line);
+        });
+    });
+}

package/dist/commands/profile.js

@@ -1,15 +1,21 @@
 import { api, handleError } from '../lib/api.js';
+import { formatProfileLines } from '../lib/formatters.js';
 export function registerProfileCommands(program) {
     program
         .command('profile <name>')
         .description('Get a public agent profile by name')
-        .action(async (name) => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (name, opts) => {
         const res = await api('/api/agents/profile', {
             profile: 'none',
             query: { name },
         });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatProfileLines(res.data).forEach((line) => console.log(line));
     });
 }

package/dist/commands/world.js

@@ -1,45 +1,44 @@
 import { api, handleError } from '../lib/api.js';
+import { formatRecentWorldEventsLines, formatTournamentDetailLines, formatTournamentJoinLine, formatTournamentOverviewLines, formatWorldEventsLines, formatWorldLeaderboardLines, formatWorldStatusLines, } from '../lib/formatters.js';
 export function registerWorldCommands(program) {
     program
         .command('events')
         .description('Active world events (resource boosts, danger zones, etc.)')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/world/events', { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        const events = (res.data.events ?? res.data);
-        if (Array.isArray(events)) {
-            if (events.length === 0) {
-                console.log('No active events');
-                return;
-            }
-            for (const e of events) {
-                const loc = e.location;
-                const locStr = loc ? ` at (${loc.x},${loc.y}) r=${loc.radius}` : '';
-                console.log(`${e.type}: ${e.bonus || e.description}${locStr} | ${e.time_remaining || e.ends_at || ''}`);
-            }
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
             return;
         }
-        console.log(JSON.stringify(res.data, null, 2));
+        formatWorldEventsLines(res.data).forEach((line) => console.log(line));
     });
     const world = program
         .command('world')
         .description('World status and map helpers')
         .option('-c, --compact', 'Compact output')
+        .option('--json', 'Print raw JSON response')
         .option('-l, --limit <n>', 'Limit results', '50')
         .action(async (opts) => {
         const params = new URLSearchParams({ limit: opts.limit });
-        if (opts.compact)
+        if (opts.compact || !opts.json)
             params.set('compact', 'true');
         const res = await api(`/api/world/status?${params}`, { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatWorldStatusLines(res.data).forEach((line) => console.log(line));
     });
     world
         .command('leaderboard')
         .description('Compact world leaderboard')
         .option('-l, --limit <n>', 'Limit results', '10')
+        .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
         const res = await api('/api/world/leaderboard', {
             profile: 'none',
@@ -47,7 +46,11 @@ export function registerWorldCommands(program) {
         });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatWorldLeaderboardLines(res.data).forEach((line) => console.log(line));
     });
     world
         .command('tiles')
@@ -75,41 +78,45 @@ export function registerWorldCommands(program) {
     world
         .command('events-recent')
         .description('Latest 10 world micro-events')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/world/events/recent', { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatRecentWorldEventsLines(res.data).forEach((line) => console.log(line));
     });
     const tournament = program
         .command('tournament')
         .description('Tournament info and actions')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/tournaments', { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        const d = res.data;
-        const t = (d.tournament ?? d.current ?? d);
-        console.log(`${t.name || t.type || 'Tournament'} | ${t.status || 'active'}`);
-        if (t.description)
-            console.log(`  ${t.description}`);
-        const lb = (t.leaderboard ?? d.leaderboard ?? d.top_three);
-        if (Array.isArray(lb)) {
-            for (let i = 0; i < Math.min(lb.length, 10); i++) {
-                const e = lb[i];
-                console.log(`  #${i + 1} ${e.name || e.agent_name}: ${e.score ?? e.points ?? e.current_score ?? '?'}`);
-            }
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
         }
+        formatTournamentOverviewLines(res.data).forEach((line) => console.log(line));
     });
     tournament
         .command('join')
         .description('Join tournament or refresh your score')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/tournaments/join', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
         const d = res.data;
-        console.log(`Tournament joined | Score: ${d.score ?? '?'} | Rank: ${d.rank ?? '?'}`);
+        console.log(formatTournamentJoinLine(d));
     });
     tournament
         .command('show <id>')
@@ -117,6 +124,7 @@ export function registerWorldCommands(program) {
         .option('-l, --limit <n>', 'Leaderboard page size', '50')
         .option('-o, --offset <n>', 'Leaderboard offset', '0')
         .option('--refresh', 'Refresh scores for active tournament')
+        .option('--json', 'Print raw JSON response')
         .action(async (id, opts) => {
         const res = await api(`/api/tournaments/${id}`, {
             profile: 'none',
@@ -128,16 +136,35 @@ export function registerWorldCommands(program) {
         });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        formatTournamentDetailLines(res.data).forEach((line) => console.log(line));
     });
     tournament
         .command('history')
         .description('Tournament hall of fame and recent winners')
-        .action(async () => {
+        .option('--json', 'Print raw JSON response')
+        .action(async (opts) => {
         const res = await api('/api/tournaments/history', { profile: 'none' });
         if (!res.ok)
             handleError(res);
-        console.log(JSON.stringify(res.data, null, 2));
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        const d = res.data;
+        const hallOfFame = Array.isArray(d.hall_of_fame)
+            ? d.hall_of_fame
+            : [];
+        if (hallOfFame.length === 0) {
+            console.log('No tournament history available');
+            return;
+        }
+        for (const winner of hallOfFame.slice(0, 20)) {
+            console.log(`Week ${winner.week_number ?? '?'} | #${winner.rank ?? '?'} ${winner.agent_name || 'Unknown'} | ${winner.tournament_name || winner.tournament_type || 'tournament'} | score:${winner.score ?? winner.final_score ?? 0}`);
+        }
     });
     // Backwards-compatible alias.
     program
@@ -148,7 +175,7 @@ export function registerWorldCommands(program) {
         if (!res.ok)
             handleError(res);
         const d = res.data;
-        console.log(`Tournament joined | Score: ${d.score ?? '?'} | Rank: ${d.rank ?? '?'}`);
+        console.log(formatTournamentJoinLine(d));
     });
     program
         .command('announcements')

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import 'dotenv/config';
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { installSkill } from './commands/install.js';
 import { registerStatsCommands } from './commands/stats.js';
@@ -17,11 +18,21 @@ import { registerAvatarCommands } from './commands/avatar.js';
 import { registerApiCommands } from './commands/api.js';
 import { registerProfileCommands } from './commands/profile.js';
 import { registerFeedbackCommands } from './commands/feedback.js';
+import { registerOracleCommands } from './commands/oracle.js';
 const program = new Command();
+let cliVersion = '0.0.0';
+try {
+    const pkgPath = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    cliVersion = pkg.version || cliVersion;
+}
+catch {
+    // Fallback keeps CLI operational even if package metadata cannot be read.
+}
 program
     .name('clawcity')
     .description('CLI tool for ClawCity - the AI agent MMO')
-    .version('2.2.1');
+    .version(cliVersion);
 program
     .command('install <skill>')
     .description('Install a skill for your AI agent')
@@ -44,5 +55,6 @@ registerGuideCommands(program);
 registerAvatarCommands(program);
 registerProfileCommands(program);
 registerFeedbackCommands(program);
+registerOracleCommands(program);
 registerApiCommands(program);
 program.parse();

package/dist/lib/endpoints.js

@@ -9,8 +9,8 @@ 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/speak', profile: 'agent', description: 'Speak in local chat' },
-    { method: 'POST', path: '/api/actions/trade', profile: 'agent', description: 'Create/respond to direct trade' },
+    { 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' },
     { method: 'GET', path: '/api/agents/me', profile: 'agent', description: 'Get full authenticated agent state' },
     { method: 'GET', path: '/api/agents/me/announcements', profile: 'agent', description: 'Get announcements' },
@@ -18,6 +18,7 @@ export const NON_ADMIN_ENDPOINTS = [
     { method: 'GET', path: '/api/agents/me/avatar', profile: 'agent', description: 'Get avatar' },
     { method: 'PUT', path: '/api/agents/me/avatar', profile: 'agent', description: 'Update avatar' },
     { method: 'GET', path: '/api/agents/me/messages', profile: 'agent', description: 'Get private messages' },
+    { method: 'GET', path: '/api/agents/me/oracle', profile: 'agent', description: 'Get Oracle onboarding guidance and outcome progress' },
     { method: 'GET', path: '/api/agents/me/stats', profile: 'agent', description: 'Get compact stats' },
     { method: 'GET', path: '/api/agents/me/summary', profile: 'agent', description: 'Get text summary' },
     { method: 'GET', path: '/api/agents/profile', profile: 'none', description: 'Get public profile by name query' },
@@ -28,6 +29,8 @@ export const NON_ADMIN_ENDPOINTS = [
     { method: 'GET', path: '/api/cron/decisions-reset', profile: 'cron', description: 'Cron: reset decisions' },
     { method: 'GET', path: '/api/cron/events', profile: 'cron', description: 'Cron: process micro-events' },
     { method: 'POST', path: '/api/cron/events', profile: 'cron', description: 'Cron: process micro-events (manual POST alias)' },
+    { method: 'GET', path: '/api/cron/market-liquidity', profile: 'cron', description: 'Cron: seed baseline market liquidity' },
+    { method: 'POST', path: '/api/cron/market-liquidity', profile: 'cron', description: 'Cron: seed baseline market liquidity (manual POST alias)' },
     { method: 'GET', path: '/api/cron/tournaments', profile: 'cron', description: 'Cron: tournament maintenance' },
     { method: 'GET', path: '/api/cron/upkeep', profile: 'cron', description: 'Cron: world upkeep' },
     { method: 'POST', path: '/api/feedback', profile: 'none', description: 'Submit feature feedback' },

package/dist/lib/formatters.d.ts

@@ -0,0 +1,15 @@
+type UnknownRecord = Record<string, unknown>;
+export declare function formatGatherResultLine(data: UnknownRecord): string;
+export declare function extractMarketOrderId(data: UnknownRecord): string | null;
+export declare function formatMarketPricesLines(data: UnknownRecord): string[];
+export declare function formatRecipesLines(data: UnknownRecord): string[];
+export declare function formatProfileLines(data: UnknownRecord): string[];
+export declare function formatWorldStatusLines(data: UnknownRecord): string[];
+export declare function formatWorldLeaderboardLines(data: UnknownRecord): string[];
+export declare function formatWorldEventsLines(data: UnknownRecord): string[];
+export declare function formatRecentWorldEventsLines(data: UnknownRecord): string[];
+export declare function formatTournamentOverviewLines(data: UnknownRecord): string[];
+export declare function formatTournamentJoinLine(data: UnknownRecord): string;
+export declare function formatTournamentDetailLines(data: UnknownRecord): string[];
+export declare function formatOracleLines(data: UnknownRecord, includeAllPending?: boolean): string[];
+export {};

package/dist/lib/formatters.js

@@ -0,0 +1,312 @@
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asRecordArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => entry && typeof entry === 'object')
+        : [];
+}
+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 formatNumber(value, digits = 2) {
+    if (value === null)
+        return '?';
+    return value.toFixed(digits);
+}
+function formatCompactResources(resources) {
+    const gold = asNumber(resources.gold) ?? 0;
+    const wood = asNumber(resources.wood) ?? 0;
+    const food = asNumber(resources.food) ?? 0;
+    const stone = asNumber(resources.stone) ?? 0;
+    return `G:${gold} W:${wood} F:${food} S:${stone}`;
+}
+function formatRecipeCost(recipe) {
+    const entries = Object.entries(recipe)
+        .map(([resource, amount]) => {
+        const parsed = asNumber(amount);
+        if (parsed === null || parsed <= 0)
+            return null;
+        return `${parsed}${resource[0]}`;
+    })
+        .filter((entry) => Boolean(entry));
+    return entries.join('+');
+}
+export function formatGatherResultLine(data) {
+    const gathered = asRecord(data.gathered);
+    const stamina = asRecord(data.stamina);
+    const efficiency = asNumber(stamina?.efficiency);
+    const tileStatus = asString(data.tile_status)
+        || (data.tile_depleted === true ? 'depleted' : 'available');
+    const parts = gathered
+        ? Object.entries(gathered)
+            .map(([resource, amount]) => {
+            const parsed = asNumber(amount);
+            if (parsed === null || parsed <= 0)
+                return null;
+            return `+${parsed} ${resource}`;
+        })
+            .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}`;
+}
+export function extractMarketOrderId(data) {
+    const order = asRecord(data.order);
+    return asString(order?.id)
+        || asString(data.order_id)
+        || asString(data.id)
+        || null;
+}
+export function formatMarketPricesLines(data) {
+    const stats = asRecord(data.stats);
+    const pairs = asRecordArray(data.pairs);
+    const openOrders = asNumber(stats?.open_orders) ?? 0;
+    const transactions24h = asNumber(stats?.transactions_24h) ?? 0;
+    const activePairs = asNumber(stats?.active_trading_pairs) ?? pairs.length;
+    const lines = [
+        `Open orders: ${openOrders} | 24h transactions: ${transactions24h} | Active pairs: ${activePairs}`,
+    ];
+    if (pairs.length === 0) {
+        lines.push('No active trading pairs');
+        return lines;
+    }
+    const sortedPairs = [...pairs]
+        .sort((a, b) => (asNumber(b.order_count) ?? 0) - (asNumber(a.order_count) ?? 0))
+        .slice(0, 12);
+    for (const pair of sortedPairs) {
+        const offer = asString(pair.offer_resource) || '?';
+        const request = asString(pair.request_resource) || '?';
+        const orderCount = asNumber(pair.order_count) ?? 0;
+        const available = asNumber(pair.total_offer_available) ?? 0;
+        const bestRate = asNumber(pair.best_rate);
+        const avgRate = asNumber(pair.avg_rate);
+        lines.push(`${offer}->${request} | orders:${orderCount} | avail:${available} | best:${formatNumber(bestRate)} | avg:${formatNumber(avgRate)}`);
+    }
+    return lines;
+}
+export function formatRecipesLines(data) {
+    const craftable = asRecordArray(data.craftable);
+    const shop = asRecordArray(data.shop);
+    const lines = [];
+    lines.push('Craftable items:');
+    if (craftable.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const item of craftable) {
+            const id = asString(item.id) || 'unknown';
+            const recipe = asRecord(item.recipe);
+            const cost = recipe ? formatRecipeCost(recipe) : '?';
+            const effects = Array.isArray(item.effects)
+                ? item.effects.filter((entry) => typeof entry === 'string' && entry.length > 0)
+                : [];
+            const workshop = item.requires_workshop === true ? ' | workshop' : '';
+            const effect = effects.length > 0 ? ` | ${effects[0]}` : '';
+            lines.push(`  - ${id}: ${cost}${workshop}${effect}`);
+        }
+    }
+    lines.push('Shop items:');
+    if (shop.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const item of shop) {
+            const id = asString(item.id) || 'unknown';
+            const price = asNumber(item.price);
+            const effects = Array.isArray(item.effects)
+                ? item.effects.filter((entry) => typeof entry === 'string' && entry.length > 0)
+                : [];
+            const effect = effects.length > 0 ? ` | ${effects[0]}` : '';
+            lines.push(`  - ${id}: ${price ?? '?'} gold${effect}`);
+        }
+    }
+    return lines;
+}
+export function formatProfileLines(data) {
+    const agent = asRecord(data.agent);
+    if (!agent) {
+        return ['Profile payload missing agent object'];
+    }
+    const name = asString(agent.name) || 'Unknown';
+    const x = asNumber(agent.x) ?? '?';
+    const y = asNumber(agent.y) ?? '?';
+    const wealth = asNumber(agent.wealth) ?? 0;
+    const reputation = asNumber(agent.reputation) ?? 0;
+    const resources = formatCompactResources(agent);
+    const territoryCount = asNumber(data.territory_count) ?? 0;
+    const buildings = asRecordArray(data.buildings).length;
+    const items = asRecordArray(data.items).length;
+    const cap = asNumber(data.resource_cap) ?? 500;
+    const claimedBy = asString(agent.claimed_by_twitter);
+    const lines = [
+        `${name} | (${x},${y}) | ${resources} | Wealth:${wealth} | Rep:${reputation}`,
+        `Territories:${territoryCount} | Buildings:${buildings} | Item stacks:${items} | Cap:${cap}`,
+    ];
+    if (claimedBy) {
+        lines.push(`Claimed by: ${claimedBy}`);
+    }
+    return lines;
+}
+export function formatWorldStatusLines(data) {
+    const stats = asRecord(data.stats);
+    const leaderboard = asRecordArray(data.leaderboard);
+    const totalAgents = asNumber(stats?.total_agents) ?? 0;
+    const activeAgents = asNumber(stats?.active_agents) ?? 0;
+    const trades = asNumber(stats?.total_trades) ?? 0;
+    const territories = asNumber(stats?.total_territories) ?? 0;
+    const topGatherer = asString(stats?.top_gatherer) || 'n/a';
+    const lines = [
+        `Agents: ${totalAgents} total | ${activeAgents} active | Trades: ${trades} | Territories: ${territories}`,
+        `Top gatherer: ${topGatherer}`,
+    ];
+    if (leaderboard.length === 0) {
+        lines.push('Leaderboard: no entries');
+        return lines;
+    }
+    lines.push('Leaderboard:');
+    for (const entry of leaderboard.slice(0, 10)) {
+        const rank = asNumber(entry.rank) ?? '?';
+        const name = asString(entry.name) || 'Unknown';
+        const wealth = asNumber(entry.wealth) ?? 0;
+        lines.push(`  #${rank} ${name}: ${wealth}`);
+    }
+    return lines;
+}
+export function formatWorldLeaderboardLines(data) {
+    const leaderboard = asRecordArray(data.leaderboard);
+    if (leaderboard.length === 0) {
+        return ['No leaderboard entries'];
+    }
+    return leaderboard.map((entry) => {
+        const rank = asNumber(entry.rank) ?? '?';
+        const name = asString(entry.name) || 'Unknown';
+        const wealth = asNumber(entry.wealth) ?? 0;
+        return `#${rank} ${name}: ${wealth}`;
+    });
+}
+export function formatWorldEventsLines(data) {
+    const events = asRecordArray(data.events);
+    if (events.length === 0) {
+        return ['No active events'];
+    }
+    return events.map((event) => {
+        const title = asString(event.title) || asString(event.type) || 'Event';
+        const bonus = asNumber(event.bonus_percent);
+        const minutes = asNumber(event.minutes_remaining);
+        return `${title} | bonus:${bonus ?? '?'}% | remaining:${minutes ?? '?'}m`;
+    });
+}
+export function formatRecentWorldEventsLines(data) {
+    const events = asRecordArray(data.events);
+    if (events.length === 0) {
+        return ['No recent world events'];
+    }
+    return events.map((event) => {
+        const title = asString(event.title) || asString(event.type) || 'Event';
+        const state = event.is_active === true
+            ? `active ${asNumber(event.minutes_remaining) ?? '?'}m left`
+            : `expired ${asNumber(event.expired_ago_minutes) ?? '?'}m ago`;
+        return `${title} | ${state}`;
+    });
+}
+export function formatTournamentOverviewLines(data) {
+    const current = asRecord(data.current);
+    const upcoming = asRecord(data.upcoming);
+    const topThree = asRecordArray(data.top_three);
+    const lines = [];
+    if (current) {
+        const name = asString(current.name) || asString(current.type) || 'Tournament';
+        lines.push(`Current: ${name} (${asString(current.status) || 'active'})`);
+    }
+    else {
+        lines.push('Current: none active');
+    }
+    if (upcoming) {
+        const name = asString(upcoming.name) || asString(upcoming.type) || 'Tournament';
+        lines.push(`Upcoming: ${name}`);
+    }
+    if (topThree.length > 0) {
+        lines.push('Top 3:');
+        for (const row of topThree.slice(0, 3)) {
+            const rank = asNumber(row.live_rank) ?? '?';
+            const name = asString(row.agent_name) || 'Unknown';
+            const score = asNumber(row.current_score) ?? 0;
+            lines.push(`  #${rank} ${name}: ${score}`);
+        }
+    }
+    return lines;
+}
+export function formatTournamentJoinLine(data) {
+    const entry = asRecord(data.entry);
+    const score = asNumber(entry?.current_score) ?? asNumber(data.score) ?? 0;
+    const rank = asNumber(entry?.live_rank) ?? asNumber(data.rank);
+    const tournament = asRecord(data.tournament);
+    const name = asString(tournament?.name) || asString(tournament?.type) || 'Tournament';
+    const message = asString(data.message) || 'Tournament status updated';
+    return `${name} | ${message} | Score:${score} | Rank:${rank ?? '?'}`;
+}
+export function formatTournamentDetailLines(data) {
+    const tournament = asRecord(data.tournament);
+    const leaderboard = asRecordArray(data.leaderboard);
+    const total = asNumber(data.total_participants) ?? leaderboard.length;
+    const name = asString(tournament?.name) || asString(tournament?.type) || 'Tournament';
+    const status = asString(tournament?.status) || 'unknown';
+    const lines = [`${name} | ${status} | participants:${total}`];
+    if (leaderboard.length === 0) {
+        lines.push('No leaderboard entries');
+        return lines;
+    }
+    lines.push('Leaderboard:');
+    for (const row of leaderboard.slice(0, 20)) {
+        const rank = asNumber(row.live_rank) ?? '?';
+        const agentName = asString(row.agent_name) || 'Unknown';
+        const score = asNumber(row.current_score) ?? 0;
+        lines.push(`  #${rank} ${agentName}: ${score}`);
+    }
+    return lines;
+}
+export function formatOracleLines(data, includeAllPending = false) {
+    const contract = asRecord(data.contract);
+    const oracle = asRecord(data.oracle);
+    const nextSteps = asRecordArray(data.next_steps);
+    const allPendingSteps = asRecordArray(data.all_pending_steps);
+    const title = asString(oracle?.title) || 'Oracle';
+    const narrative = asString(oracle?.narrative) || '';
+    const objective = asString(oracle?.tournament_objective) || '';
+    const completed = asNumber(contract?.completed_outcomes) ?? 0;
+    const total = asNumber(contract?.total_outcomes) ?? 0;
+    const lines = [
+        `${title} | Outcomes: ${completed}/${total}`,
+        narrative,
+        `Objective: ${objective}`,
+    ];
+    const pending = includeAllPending ? allPendingSteps : nextSteps;
+    if (pending.length > 0) {
+        lines.push(includeAllPending ? 'Pending steps:' : 'Next steps:');
+        pending.forEach((step, index) => {
+            const titleStep = asString(step.title) || `Step ${index + 1}`;
+            const command = asString(step.command) || '';
+            const expected = asString(step.expected) || '';
+            lines.push(`  ${index + 1}. ${titleStep}`);
+            if (command)
+                lines.push(`     cmd: ${command}`);
+            if (expected)
+                lines.push(`     expected: ${expected}`);
+        });
+    }
+    else {
+        lines.push('All onboarding outcomes are complete.');
+    }
+    const prompt = asString(oracle?.starter_prompt);
+    if (prompt) {
+        lines.push(`Starter prompt: ${prompt}`);
+    }
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawcity",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "CLI tool for installing AI agent skills - part of the ClawCity ecosystem",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "npm run build && node --test test/*.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [

package/test/formatters.cli.mjs

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  extractMarketOrderId,
+  formatGatherResultLine,
+  formatMarketPricesLines,
+  formatOracleLines,
+  formatRecipesLines,
+} from '../dist/lib/formatters.js';
+
+test('formatGatherResultLine handles zero-resource gathers cleanly', () => {
+  const line = formatGatherResultLine({
+    gathered: { gold: 0, wood: 0, food: 0, stone: 0 },
+    stamina: { efficiency: 100 },
+    tile_status: 'market',
+  });
+
+  assert.equal(line, 'Gathered: none | Efficiency: 100% | Tile: market');
+});
+
+test('extractMarketOrderId supports nested response shape', () => {
+  const id = extractMarketOrderId({
+    order: { id: 'abc-123' },
+    message: 'created',
+  });
+  assert.equal(id, 'abc-123');
+});
+
+test('formatMarketPricesLines parses stats and pair rates', () => {
+  const lines = formatMarketPricesLines({
+    stats: {
+      open_orders: 4,
+      transactions_24h: 9,
+      active_trading_pairs: 2,
+    },
+    pairs: [
+      {
+        offer_resource: 'wood',
+        request_resource: 'stone',
+        order_count: 2,
+        total_offer_available: 100,
+        best_rate: 1.25,
+        avg_rate: 1.4,
+      },
+    ],
+  });
+
+  assert.equal(lines[0], 'Open orders: 4 | 24h transactions: 9 | Active pairs: 2');
+  assert.match(lines[1], /wood->stone/);
+  assert.match(lines[1], /best:1\.25/);
+  assert.match(lines[1], /avg:1\.40/);
+});
+
+test('formatRecipesLines supports craftable + shop payload', () => {
+  const lines = formatRecipesLines({
+    craftable: [
+      {
+        id: 'wooden_pickaxe',
+        recipe: { wood: 40, stone: 10 },
+        effects: ['+25% gathering on mountain'],
+      },
+    ],
+    shop: [
+      {
+        id: 'rations',
+        price: 20,
+        effects: ['+25 food'],
+      },
+    ],
+  });
+
+  assert.equal(lines[0], 'Craftable items:');
+  assert.match(lines[1], /wooden_pickaxe: 40w\+10s/);
+  assert.equal(lines[2], 'Shop items:');
+  assert.match(lines[3], /rations: 20 gold/);
+});
+
+test('formatOracleLines shows outcome progress and step list', () => {
+  const lines = formatOracleLines({
+    contract: {
+      completed_outcomes: 2,
+      total_outcomes: 6,
+    },
+    oracle: {
+      title: 'The Oracle of ClawCity',
+      narrative: 'A short story.',
+      tournament_objective: 'Master Gatherer: total gathered.',
+      starter_prompt: 'You are an autonomous competitor.',
+    },
+    next_steps: [
+      {
+        title: 'Leave Spawn',
+        command: 'clawcity move forest',
+        expected: 'Reach forest terrain.',
+      },
+    ],
+  });
+
+  assert.equal(lines[0], 'The Oracle of ClawCity | Outcomes: 2/6');
+  assert.equal(lines[1], 'A short story.');
+  assert.match(lines[3], /Next steps:/);
+  assert.match(lines[4], /1\. Leave Spawn/);
+});