@pleri/olam-cli 0.1.144 → 0.1.145

package/dist/commands/memory/stats.js

@@ -0,0 +1,164 @@
+/**
+ * olam memory stats — operator-facing formatter over `/bridge/stats`.
+ *
+ *   $ olam memory stats
+ *     # human-readable counters + derived cache_error_rate
+ *
+ *   $ olam memory stats --json
+ *     # raw /bridge/stats response (for jq / monitoring scripts)
+ *
+ * Config (env vars):
+ *   AGENTMEMORY_BRIDGE_URL    bridge base URL
+ *                             (default: https://olam-agent-memory.ernestcodes.workers.dev)
+ *   AGENTMEMORY_BRIDGE_SECRET bearer token
+ *
+ * Derived metric: cache_error_rate =
+ *     (cache_busted_hash + cache_busted_version) / max(writes_observed, 1)
+ *
+ *   Interpretation: high rates (>5%) mean operators have been forced to
+ *   reclassify a lot of recent writes — usually a sign that the prompt
+ *   template / classifier_version is churning. The denominator is
+ *   classifier_writes_observed (NOT bridge writes_observed).
+ *
+ * Plan reference:
+ *   docs/plans/agentmemory-classifier-and-regret/phase-b-tasks.md (B5/B6)
+ */
+import { printError, printHeader, printInfo } from '../../output.js';
+const DEFAULT_BRIDGE_URL = 'https://olam-agent-memory.ernestcodes.workers.dev';
+const STATS_TIMEOUT_MS = 10_000;
+/**
+ * Pure helper — separated so it's unit-testable without HTTP.
+ * Guards divide-by-zero (returns 0 when writes_observed === 0, even
+ * if busts are nonzero — Infinity / NaN would be operator-hostile).
+ */
+export function computeCacheErrorRate(counters) {
+    if (counters.writes_observed <= 0)
+        return 0;
+    const busted = counters.cache_busted_hash + counters.cache_busted_version;
+    return busted / counters.writes_observed;
+}
+function resolveBridgeUrl(opts) {
+    return opts.bridgeUrl
+        ?? process.env['AGENTMEMORY_BRIDGE_URL']
+        ?? DEFAULT_BRIDGE_URL;
+}
+function resolveBearer(opts) {
+    const fromOpt = opts.bearer;
+    if (fromOpt && fromOpt.length > 0)
+        return fromOpt;
+    const fromEnv = process.env['AGENTMEMORY_BRIDGE_SECRET'];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return null;
+}
+function intOrZero(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return 0;
+    return Math.trunc(v);
+}
+function extractCounters(stats) {
+    return {
+        writes_observed: intOrZero(stats.classifier_writes_observed),
+        writes_deduped_hash: intOrZero(stats.classifier_writes_deduped_hash),
+        writes_deduped_semantic: intOrZero(stats.classifier_writes_deduped_semantic),
+        recalls_observed: intOrZero(stats.classifier_recalls_observed),
+        cache_busted_hash: intOrZero(stats.classifier_cache_busted_hash),
+        cache_busted_version: intOrZero(stats.classifier_cache_busted_version),
+    };
+}
+/**
+ * Run the stats call. Pure-ish: takes opts + fetch (so tests can stub) +
+ * returns a structured result. Mirrors `runReclassify` for symmetry.
+ */
+export async function runStats(opts, fetchImpl = fetch) {
+    const bridgeUrl = resolveBridgeUrl(opts);
+    const bearer = resolveBearer(opts);
+    if (!bearer) {
+        return {
+            ok: false,
+            error: 'AGENTMEMORY_BRIDGE_SECRET not set (or --bearer not passed)',
+        };
+    }
+    try {
+        const res = await fetchImpl(`${bridgeUrl}/bridge/stats`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${bearer}`,
+            },
+            signal: AbortSignal.timeout(STATS_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            return {
+                ok: false,
+                error: `bridge returned ${res.status} ${res.statusText}${detail ? `: ${detail.slice(0, 200)}` : ''}`,
+            };
+        }
+        const payload = (await res.json());
+        if (!payload || typeof payload !== 'object' || !payload.stats || typeof payload.stats !== 'object') {
+            return {
+                ok: false,
+                error: 'bridge response missing stats envelope',
+            };
+        }
+        const counters = extractCounters(payload.stats);
+        const cacheErrorRate = computeCacheErrorRate(counters);
+        return {
+            ok: true,
+            counters,
+            cacheErrorRate,
+            raw: payload,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function formatPct(numerator, denominator) {
+    if (denominator <= 0)
+        return '0.0%';
+    return `${((numerator / denominator) * 100).toFixed(1)}%`;
+}
+/** Run + render. Returns the process exit code. */
+export async function runStatsCli(opts) {
+    const result = await runStats(opts);
+    if (opts.json) {
+        // Preserve the raw bridge envelope when possible so jq pipelines
+        // see the same shape they'd get from curl. Fall back to the
+        // structured result on error so callers can still inspect.
+        const out = result.ok && result.raw !== undefined ? result.raw : result;
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        return result.ok ? 0 : 1;
+    }
+    printHeader('olam memory stats — bridge counters');
+    if (!result.ok) {
+        printError(`stats failed: ${result.error ?? '(unknown error)'}`);
+        return 1;
+    }
+    const c = result.counters;
+    printInfo('writes_observed', String(c.writes_observed));
+    printInfo('writes_deduped_hash', `${c.writes_deduped_hash}  (${formatPct(c.writes_deduped_hash, c.writes_observed)})`);
+    printInfo('writes_deduped_semantic', `${c.writes_deduped_semantic}  (${formatPct(c.writes_deduped_semantic, c.writes_observed)})`);
+    printInfo('recalls_observed', String(c.recalls_observed));
+    printInfo('cache_busted_hash', String(c.cache_busted_hash));
+    printInfo('cache_busted_version', String(c.cache_busted_version));
+    printInfo('cache_error_rate', `${(result.cacheErrorRate * 100).toFixed(1)}%`);
+    return 0;
+}
+export function registerMemoryStats(cmd) {
+    cmd
+        .command('stats')
+        .description('Fetch /bridge/stats from the agent-memory bridge and format classifier counters (writes_observed, dedup rates, recalls, cache busts, derived cache_error_rate)')
+        .option('--bridge-url <url>', 'Override AGENTMEMORY_BRIDGE_URL')
+        .option('--bearer <token>', 'Override AGENTMEMORY_BRIDGE_SECRET')
+        .option('--json', 'Machine-readable JSON output (raw bridge envelope)', false)
+        .action(async (opts) => {
+        const rc = await runStatsCli(opts);
+        if (rc !== 0)
+            process.exitCode = rc;
+    });
+}
+//# sourceMappingURL=stats.js.map

package/dist/commands/memory/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/commands/memory/stats.ts"],"names":[],"mappings":"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"}

package/dist/commands/skills-source.d.ts

@@ -0,0 +1,12 @@
+/**
+ * olam skills source — manage registered skill sources.
+ *
+ *   olam skills source list
+ *   olam skills source add --name <n> --git-url <url> [--branch <b>]
+ *   olam skills source remove <id>
+ *   olam skills source pull <id>
+ *   olam skills source show <id>
+ */
+import type { Command } from 'commander';
+export declare function registerSkillsSource(program: Command): void;
+//# sourceMappingURL=skills-source.d.ts.map

package/dist/commands/skills-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-source.d.ts","sourceRoot":"","sources":["../../src/commands/skills-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2H3D"}

package/dist/commands/skills-source.js

@@ -0,0 +1,133 @@
+/**
+ * olam skills source — manage registered skill sources.
+ *
+ *   olam skills source list
+ *   olam skills source add --name <n> --git-url <url> [--branch <b>]
+ *   olam skills source remove <id>
+ *   olam skills source pull <id>
+ *   olam skills source show <id>
+ */
+import pc from 'picocolors';
+import { listSkillSources, getSkillSource, addSkillSource, removeSkillSource, updateSkillSource, cloneSkillSource, pullSkillSource, removeSkillSourceClone, skillSourceClonePath, } from '@olam/core/src/skill-sources/index.js';
+import { printError, printSuccess, printHeader } from '../output.js';
+function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function registerSkillsSource(program) {
+    const skills = program.command('skills').description('Manage skill sources and synchronization');
+    const source = skills.command('source').description('Manage registered skill sources');
+    source
+        .command('list')
+        .description('List all registered skill sources')
+        .action(() => {
+        const all = listSkillSources();
+        if (all.length === 0) {
+            console.log(pc.dim('0 skill source(s) registered. Add one with: olam skills source add --name <n> --git-url <url>'));
+            return;
+        }
+        printHeader(`${all.length} skill source(s)`);
+        for (const s of all) {
+            const when = new Date(s.addedAt).toISOString().slice(0, 10);
+            const sha = s.lastPulledSha ? s.lastPulledSha.slice(0, 8) : pc.dim('(unpulled)');
+            console.log(`  ${pc.bold(s.id.padEnd(14))} ${s.name.padEnd(24)} ${s.branch.padEnd(12)} ${sha.padEnd(12)} ${pc.dim(when)} ${pc.dim(s.gitUrl)}`);
+        }
+    });
+    source
+        .command('add')
+        .description('Register and clone a skill source')
+        .requiredOption('--name <name>', 'Display name (lowercase, digits, dash)')
+        .requiredOption('--git-url <url>', 'git URL (https://, git@, ssh://, file://, or absolute path)')
+        .option('--branch <branch>', 'Branch to track', 'main')
+        .action((opts) => {
+        let entry;
+        try {
+            entry = addSkillSource({ name: opts.name, gitUrl: opts.gitUrl, branch: opts.branch });
+        }
+        catch (err) {
+            printError(asMessage(err));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = cloneSkillSource({
+                gitUrl: entry.gitUrl,
+                branch: entry.branch,
+                id: entry.id,
+            });
+            updateSkillSource(entry.id, { lastPulledSha: result.headSha });
+            printSuccess(`registered skill source "${entry.name}" (${entry.id}) at ${result.clonePath} @ ${result.headSha.slice(0, 8)}`);
+        }
+        catch (err) {
+            // Roll back the state-store entry so add stays atomic
+            try {
+                removeSkillSource(entry.id);
+            }
+            catch {
+                // best-effort rollback
+            }
+            printError(asMessage(err));
+            process.exitCode = 1;
+        }
+    });
+    source
+        .command('remove')
+        .description('Remove a registered skill source (deletes its clone)')
+        .argument('<id>', 'Skill source id (from "olam skills source list")')
+        .action((id) => {
+        try {
+            removeSkillSourceClone(id);
+            removeSkillSource(id);
+            printSuccess(`removed skill source "${id}"`);
+        }
+        catch (err) {
+            printError(asMessage(err));
+            process.exitCode = 1;
+        }
+    });
+    source
+        .command('pull')
+        .description('Fetch + reset the clone to upstream HEAD')
+        .argument('<id>', 'Skill source id')
+        .action((id) => {
+        try {
+            const entry = getSkillSource(id);
+            if (!entry) {
+                printError(`skill source "${id}" is not registered`);
+                process.exitCode = 1;
+                return;
+            }
+            const result = pullSkillSource({
+                gitUrl: entry.gitUrl,
+                branch: entry.branch,
+                id: entry.id,
+            });
+            updateSkillSource(entry.id, { lastPulledSha: result.headSha });
+            printSuccess(`pulled "${entry.name}" → ${result.headSha.slice(0, 8)}`);
+        }
+        catch (err) {
+            printError(asMessage(err));
+            process.exitCode = 1;
+        }
+    });
+    source
+        .command('show')
+        .description('Show details for a single skill source')
+        .argument('<id>', 'Skill source id')
+        .action((id) => {
+        const entry = getSkillSource(id);
+        if (!entry) {
+            printError(`skill source "${id}" is not registered`);
+            process.exitCode = 1;
+            return;
+        }
+        const when = new Date(entry.addedAt).toISOString();
+        console.log(`${pc.bold('id:')}            ${entry.id}`);
+        console.log(`${pc.bold('name:')}          ${entry.name}`);
+        console.log(`${pc.bold('gitUrl:')}        ${entry.gitUrl}`);
+        console.log(`${pc.bold('branch:')}        ${entry.branch}`);
+        console.log(`${pc.bold('addedAt:')}       ${when}`);
+        console.log(`${pc.bold('lastPulledSha:')} ${entry.lastPulledSha ?? pc.dim('(unpulled)')}`);
+        console.log(`${pc.bold('clonePath:')}     ${skillSourceClonePath(entry.id)}`);
+    });
+}
+//# sourceMappingURL=skills-source.js.map

package/dist/commands/skills-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-source.js","sourceRoot":"","sources":["../../src/commands/skills-source.ts"],"names":[],"mappings":"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"}

package/dist/commands/skills.d.ts

@@ -0,0 +1,11 @@
+/**
+ * olam skills — sync, dry-run/diff, list-installed, show.
+ *
+ *   olam skills sync [--dry-run] [--atlas-user <u>]
+ *   olam skills diff [--atlas-user <u>]            (alias of `sync --dry-run`)
+ *   olam skills list                                (lists deployed artifacts)
+ *   olam skills show <name>                         (shows details for a deployed artifact)
+ */
+import type { Command } from 'commander';
+export declare function registerSkills(program: Command): void;
+//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0FzC,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgFrD"}

package/dist/commands/skills.js

@@ -0,0 +1,163 @@
+/**
+ * olam skills — sync, dry-run/diff, list-installed, show.
+ *
+ *   olam skills sync [--dry-run] [--atlas-user <u>]
+ *   olam skills diff [--atlas-user <u>]            (alias of `sync --dry-run`)
+ *   olam skills list                                (lists deployed artifacts)
+ *   olam skills show <name>                         (shows details for a deployed artifact)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import pc from 'picocolors';
+import { syncSkills, claudeDir, listSkillSources, skillSourceClonePath, } from '@olam/core/src/skill-sources/index.js';
+import { printError, printSuccess, printHeader } from '../output.js';
+function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function listDeployed() {
+    const dir = claudeDir();
+    const sources = listSkillSources();
+    const sourcePaths = new Map(sources.map((s) => [skillSourceClonePath(s.id), s.id]));
+    const entries = [];
+    for (const bucket of ['skills', 'agents', 'scripts', 'rules', 'commands']) {
+        const bucketDir = path.join(dir, bucket);
+        if (!fs.existsSync(bucketDir))
+            continue;
+        for (const name of fs.readdirSync(bucketDir)) {
+            const full = path.join(bucketDir, name);
+            try {
+                const stat = fs.lstatSync(full);
+                if (!stat.isSymbolicLink())
+                    continue;
+                const target = fs.readlinkSync(full);
+                let sourceId;
+                for (const [clonePath, id] of sourcePaths.entries()) {
+                    if (target.startsWith(clonePath)) {
+                        sourceId = id;
+                        break;
+                    }
+                }
+                entries.push({ bucket, name, target, sourceId });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return entries;
+}
+function printSyncSummary(summary, dryRun) {
+    printHeader(dryRun ? 'dry-run summary' : 'sync summary');
+    console.log(`  sources:         ${summary.sourceCount}`);
+    console.log(`  artifacts:       ${summary.artifactCount}`);
+    console.log(`  hook files:      ${summary.hookFileCount}`);
+    console.log(`  permission files:${summary.permissionFileCount}`);
+    if (summary.deploy) {
+        console.log(`  symlinks made:   ${summary.deploy.linked}`);
+        if (summary.deploy.shadowBackups.length > 0) {
+            console.log(`  ${pc.yellow('shadow backups:')} ${summary.deploy.shadowBackups.length}`);
+            for (const p of summary.deploy.shadowBackups)
+                console.log(`    ${pc.dim(p)}`);
+        }
+        if (summary.deploy.subagentCollisions.length > 0) {
+            console.log(`  ${pc.yellow('agent name collisions:')} ${summary.deploy.subagentCollisions.length}`);
+            for (const c of summary.deploy.subagentCollisions) {
+                console.log(`    ${pc.bold(c.name)} → winner: ${pc.dim(c.winner)}`);
+                for (const l of c.losers)
+                    console.log(`      ${pc.dim('(skipped)')} ${l}`);
+            }
+        }
+    }
+    if (summary.merge) {
+        console.log(`  hooks added:     ${summary.merge.hooksAdded}`);
+        console.log(`  permissions:     ${summary.merge.permissionsCount}`);
+        if (summary.merge.backupPath) {
+            console.log(`  settings backup: ${pc.dim(summary.merge.backupPath)}`);
+        }
+    }
+    console.log();
+    for (const s of summary.perSource) {
+        const sub = s.fromSubscriptionsFile ? '(subscribed)' : '(all categories)';
+        console.log(`  ${pc.bold(s.name.padEnd(24))} ${s.artifactCount} artifacts · ${s.categories.join(', ') || '(none)'} ${pc.dim(sub)}`);
+    }
+}
+export function registerSkills(program) {
+    const skills = program.commands.find((c) => c.name() === 'skills') ?? program.command('skills').description('Manage skill sources and synchronization');
+    skills
+        .command('sync')
+        .description('Sync registered skill sources to ~/.claude/')
+        .option('--dry-run', 'Resolve artifacts but do not deploy or merge')
+        .option('--atlas-user <user>', 'Override atlas-user (defaults to ~/.claude/.atlas-user)')
+        .action(async (opts) => {
+        try {
+            const summary = await syncSkills({ dryRun: opts.dryRun, atlasUser: opts.atlasUser });
+            printSyncSummary(summary, !!opts.dryRun);
+            if (!opts.dryRun) {
+                printSuccess(`synced ${summary.sourceCount} source(s), ${summary.artifactCount} artifact(s)`);
+            }
+        }
+        catch (err) {
+            printError(asMessage(err));
+            process.exitCode = 1;
+        }
+    });
+    skills
+        .command('diff')
+        .description('Show what `olam skills sync` would deploy (no on-disk changes)')
+        .option('--atlas-user <user>', 'Override atlas-user')
+        .action(async (opts) => {
+        try {
+            const summary = await syncSkills({ dryRun: true, atlasUser: opts.atlasUser });
+            printSyncSummary(summary, true);
+        }
+        catch (err) {
+            printError(asMessage(err));
+            process.exitCode = 1;
+        }
+    });
+    skills
+        .command('list')
+        .description('List artifacts currently deployed to ~/.claude/')
+        .action(() => {
+        const entries = listDeployed();
+        if (entries.length === 0) {
+            console.log(pc.dim('0 deployed artifact(s). Run "olam skills sync" first.'));
+            return;
+        }
+        const byBucket = new Map();
+        for (const e of entries) {
+            const list = byBucket.get(e.bucket) ?? [];
+            list.push(e);
+            byBucket.set(e.bucket, list);
+        }
+        printHeader(`${entries.length} deployed artifact(s)`);
+        for (const [bucket, list] of byBucket.entries()) {
+            console.log(`  ${pc.bold(bucket)} (${list.length})`);
+            for (const e of list) {
+                const src = e.sourceId ? `[${e.sourceId}]` : pc.yellow('[unknown]');
+                console.log(`    ${e.name.padEnd(40)} ${pc.dim(src)} → ${pc.dim(e.target)}`);
+            }
+        }
+    });
+    skills
+        .command('show')
+        .description('Show details for a deployed artifact (by name)')
+        .argument('<name>', 'Artifact name (e.g. plan-hard, codex-second-opinion.md)')
+        .action((name) => {
+        const entries = listDeployed();
+        const matches = entries.filter((e) => e.name === name);
+        if (matches.length === 0) {
+            printError(`no deployed artifact matches "${name}"`);
+            process.exitCode = 1;
+            return;
+        }
+        for (const e of matches) {
+            console.log(`${pc.bold('bucket:')}   ${e.bucket}`);
+            console.log(`${pc.bold('name:')}     ${e.name}`);
+            console.log(`${pc.bold('target:')}   ${e.target}`);
+            console.log(`${pc.bold('source:')}   ${e.sourceId ?? pc.dim('(unknown — not from a registered olam source)')}`);
+            console.log();
+        }
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"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"}

package/dist/commands/status.d.ts

@@ -11,6 +11,33 @@
  * transitive @olam/adapters resolution.
  */
 import type { Command } from 'commander';
+/**
+ * Canonical runtime-state contract per Decision 17. Surfaced by host-cp's
+ * `GET /v1/worlds/:id/status` endpoint; both Docker and Kubernetes engines
+ * map their native state onto this shape so the wire-format is identical.
+ */
+export interface WorldRuntimeStatus {
+    readonly state: 'running' | 'starting' | 'stopped' | 'crashed' | 'unknown';
+    readonly ready_replicas: number;
+    readonly restarts: number;
+    readonly last_event_type: string | null;
+    readonly last_event_age_seconds: number | null;
+}
+/**
+ * Parse and validate a server response payload into WorldRuntimeStatus.
+ * Returns null on any shape mismatch so the caller falls back gracefully.
+ * Exported for unit testing.
+ */
+export declare function parseRuntimeStatus(raw: unknown): WorldRuntimeStatus | null;
+export type FetchRuntimeFn = (worldId: string, token: string) => Promise<WorldRuntimeStatus | null>;
+/**
+ * Default fetcher — hits host-cp's /v1/worlds/:id/status via the loopback
+ * port with a 2-second timeout. Returns null on any error so the calling
+ * `olam status` command renders the registry view without the runtime
+ * block when host-cp is down or the engine fails (preserves the legacy
+ * behaviour for operators with a stopped host-cp).
+ */
+export declare const fetchWorldRuntimeStatus: FetchRuntimeFn;
 export interface MachineStatus {
     readonly version: string;
     readonly port: number;

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAC9C,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC;IACxC,GAAG,EAAE;QAAE,YAAY,EAAE;YAAE,UAAU,EAAE,MAAM,OAAO,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACtB,CAAC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,CAAC,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,aAAa,EACxB,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,aAAa,CAAC,CAoDxB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyErD"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAqB1E;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,cA6BlC,CAAC;AAEL,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAC9C,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC;IACxC,GAAG,EAAE;QAAE,YAAY,EAAE;YAAE,UAAU,EAAE,MAAM,OAAO,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACtB,CAAC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,CAAC,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,aAAa,EACxB,UAAU,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,aAAa,CAAC,CAoDxB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqGrD"}