@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/commands/feedback.js

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs';
+import { ABX_FEEDBACK_AREAS, AbxServiceClient, FEEDBACK_KINDS, FEEDBACK_SEVERITIES, SERVICE_FEEDBACK_INTERFACE, } from '@artblocks/abx-sdk';
+import { bold, dim, info, ok } from '../output.js';
+import { ABX_SERVICES_URL, requireRemoteToken, resolveRemote, serviceClient, } from '../remote.js';
+import { readCliVersion } from '../update-check.js';
+function value(flags, key) {
+    const raw = flags[key];
+    return typeof raw === 'string' && raw !== 'true' ? raw : undefined;
+}
+function oneOf(raw, choices, flag) {
+    if (raw === undefined)
+        return undefined;
+    if (choices.includes(raw))
+        return raw;
+    throw new Error(`${flag} must be one of: ${choices.join(', ')}`);
+}
+function jsonObject(text, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${source} must contain valid JSON`);
+    }
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+        throw new Error(`${source} must be a JSON object`);
+    }
+    return parsed;
+}
+function fileOrFlag(flags, flag, fileFlag) {
+    const direct = value(flags, flag);
+    const path = value(flags, fileFlag);
+    if (direct && path)
+        throw new Error(`use --${flag} or --${fileFlag}, not both`);
+    return path ? readFileSync(path, 'utf8') : direct;
+}
+/** Pure report construction: validate locally so a preview is the exact body that --yes sends. */
+export function buildFeedbackReport(flags, target) {
+    const summary = value(flags, 'summary');
+    if (!summary)
+        return null;
+    const kind = oneOf(value(flags, 'kind'), FEEDBACK_KINDS, '--kind');
+    if (!kind)
+        throw new Error(`--kind is required with --summary (${FEEDBACK_KINDS.join(', ')})`);
+    const severity = oneOf(value(flags, 'severity'), FEEDBACK_SEVERITIES, '--severity');
+    const via = oneOf(value(flags, 'via'), ['agent', 'human'], '--via');
+    const detail = fileOrFlag(flags, 'detail', 'detail-file');
+    const contextRaw = fileOrFlag(flags, 'context', 'context-file');
+    const context = {
+        ...(contextRaw ? jsonObject(contextRaw, value(flags, 'context-file') ? '--context-file' : '--context') : {}),
+        cliVersion: readCliVersion(),
+    };
+    const shared = { kind: kind, summary, detail, severity: severity, via, context };
+    if (target === 'abx') {
+        if (value(flags, 'component'))
+            throw new Error('--component is for --remote provider feedback; use --area for core ABX');
+        const area = oneOf(value(flags, 'area'), ABX_FEEDBACK_AREAS, '--area');
+        if (!area)
+            throw new Error(`--area is required for core ABX feedback (${ABX_FEEDBACK_AREAS.join(', ')})`);
+        return { area, ...shared };
+    }
+    if (value(flags, 'area'))
+        throw new Error('--area is for core ABX feedback; use --component with --remote');
+    return { component: value(flags, 'component'), ...shared };
+}
+async function targetFor(flags, env = process.env) {
+    const tokenFlag = value(flags, 'remote-token');
+    if (flags.remote === undefined) {
+        const remote = resolveRemote('abx', tokenFlag, env);
+        return {
+            kind: 'abx',
+            label: 'core ABX',
+            endpoint: `${ABX_SERVICES_URL}/abx/feedback`,
+            remote,
+            // The generic SDK feedback paths become /abx/feedback and /abx/feedback/mine.
+            client: new AbxServiceClient({ baseUrl: `${ABX_SERVICES_URL}/abx`, token: remote.token }),
+        };
+    }
+    const remote = resolveRemote(String(flags.remote), tokenFlag, env);
+    if (!remote)
+        throw new Error('--remote needs a provider name or URL');
+    const client = serviceClient(remote);
+    const descriptor = await client.descriptor();
+    if (!descriptor.interfaces?.includes(SERVICE_FEEDBACK_INTERFACE)) {
+        throw new Error(`${remote.url} does not declare ${SERVICE_FEEDBACK_INTERFACE}; provider feedback is not supported there. ` +
+            `Core ABX feedback is the default: run abx feedback without --remote.`);
+    }
+    return { kind: 'service', label: `provider ${remote.name?.toLowerCase() ?? remote.url}`, endpoint: `${remote.url}/feedback`, remote, client };
+}
+/** Core ABX by default; `--remote <provider>` switches to that provider's standard feedback path. */
+export async function cmdFeedback(flags) {
+    const target = await targetFor(flags);
+    const report = buildFeedbackReport(flags, target.kind);
+    const mine = flags.mine !== undefined;
+    const json = flags.json !== undefined;
+    if (mine && report)
+        throw new Error('--mine cannot be combined with --summary');
+    if (mine) {
+        requireRemoteToken(target.remote);
+        const limitRaw = value(flags, 'limit');
+        const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+        if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0))
+            throw new Error('--limit must be a positive integer');
+        const rows = await target.client.listFeedback({
+            area: target.kind === 'abx' ? value(flags, 'area') : undefined,
+            component: target.kind === 'service' ? value(flags, 'component') : undefined,
+            kind: oneOf(value(flags, 'kind'), FEEDBACK_KINDS, '--kind'),
+            limit,
+        });
+        if (json)
+            console.log(JSON.stringify({ target: target.kind, feedback: rows }, null, 2));
+        else {
+            console.log(`\n  ${bold(`${target.label} feedback`)}  ${dim(`${rows.length} report(s)`)}`);
+            for (const row of rows)
+                console.log(`    ${row.id}  ${row.kind}  ${row.summary}`);
+            console.log('');
+        }
+        return;
+    }
+    if (!report) {
+        const instructions = await target.client.feedbackInstructions();
+        if (json)
+            console.log(JSON.stringify(instructions, null, 2));
+        else
+            console.log(`\n${JSON.stringify(instructions, null, 2)}\n`);
+        return;
+    }
+    if (flags.yes === undefined) {
+        const preview = { submitted: false, target: target.kind, endpoint: target.endpoint, report };
+        if (json)
+            console.log(JSON.stringify(preview, null, 2));
+        else {
+            console.log(`\n  ${bold('feedback preview')}  ${dim(`→ ${target.endpoint}`)}`);
+            console.log(JSON.stringify(report, null, 2));
+            info('Report content not sent. Review/redact it, obtain human approval, then re-run with --yes.');
+            console.log('');
+        }
+        return;
+    }
+    requireRemoteToken(target.remote);
+    const result = await target.client.submitFeedback(report);
+    if (json)
+        console.log(JSON.stringify({ submitted: true, target: target.kind, ...result }, null, 2));
+    else
+        ok(`${target.label} feedback recorded (${result.id})`);
+}
+//# sourceMappingURL=feedback.js.map

package/dist/commands/feedback.js.map

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

package/dist/commands/maintenance.d.ts

@@ -0,0 +1,4 @@
+import { type Flags } from '../flags.js';
+export declare function cmdVacuum(rest: string[], flags: Flags): Promise<void>;
+export declare const VACUUM_HELP: string;
+//# sourceMappingURL=maintenance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../src/commands/maintenance.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAC,KAAK,KAAK,EAAC,MAAM,aAAa,CAAC;AAiBvC,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3E;AA8DD,eAAO,MAAM,WAAW,QAQ8D,CAAC"}

package/dist/commands/maintenance.js

@@ -0,0 +1,114 @@
+/**
+ * `abx vacuum` — SQLite maintenance for the local reference store (issue #113).
+ *
+ * Two halves, matching `SqliteStore`'s split in `packages/indexer/src/store.ts`:
+ *  - `abx vacuum convert`     the one-time, EXPLICIT full `VACUUM` for a store stuck at
+ *                             `auto_vacuum='none'` — every store created before this repo started
+ *                             setting the pragma ahead of schema creation (and, until the pragma
+ *                             ordering bug this issue also fixed, every store created since too —
+ *                             see the comment on `SCHEMA` in store.ts). A full VACUUM rewrites the
+ *                             ENTIRE database file and can briefly need up to ~2x its on-disk size,
+ *                             so it never runs on its own anywhere in this codebase — this command
+ *                             is the only place it happens, and only when an operator asks for it.
+ *  - `abx vacuum incremental` a manual, bounded `PRAGMA incremental_vacuum` pass — the SAME bounded
+ *                             mechanism `abx serve` already runs automatically BETWEEN watch-loop
+ *                             ticks (`SelfHostIndexer.startVacuumMaintenance`), exposed here for an
+ *                             operator who wants one pass on demand (right after `convert`, or on a
+ *                             node that isn't running `abx serve`'s watcher at all).
+ *
+ * `abx vacuum` (or `abx vacuum status`) alone is read-only: it just reports where the store stands,
+ * so an operator can decide whether either half applies before running anything.
+ */
+import { DEFAULT_INCREMENTAL_VACUUM_PAGES, SqliteStore } from '@artblocks/abx-indexer';
+import { localIndexer } from '../config.js';
+import { bold, dim, g, info, ok, warn } from '../output.js';
+/** Vacuuming is SQLite-specific (see store.ts's docstring on why these methods aren't on the
+ *  generic `Store` interface) — a platform-scale Postgres deploy has its own manual VACUUM story
+ *  outside this codebase, so this command has nothing to do there and says so plainly. */
+function requireSqliteStore() {
+    const store = localIndexer().store;
+    if (!(store instanceof SqliteStore)) {
+        throw new Error('abx vacuum applies to the local SQLite reference store only — this node is backed by something else, ' +
+            'which owns its own maintenance story.');
+    }
+    return store;
+}
+export async function cmdVacuum(rest, flags) {
+    const sub = rest[0];
+    switch (sub) {
+        case undefined:
+        case 'status':
+            return cmdVacuumStatus();
+        case 'convert':
+            return cmdVacuumConvert();
+        case 'incremental':
+            return cmdVacuumIncremental(flags);
+        default:
+            console.error(VACUUM_USAGE);
+            process.exitCode = 1;
+    }
+}
+function cmdVacuumStatus() {
+    const store = requireSqliteStore();
+    const stats = store.vacuumStats();
+    console.log(`store        ${store.path}`);
+    console.log(`auto_vacuum  ${bold(stats.mode)}`);
+    console.log(`page_count   ${stats.pageCount}`);
+    console.log(`freelist     ${stats.freelistPages} page(s)`);
+    console.log('');
+    if (stats.mode === 'none') {
+        warn(`this store predates incremental auto-vacuum and needs a one-time conversion: ${g('abx vacuum convert')}`);
+    }
+    else if (stats.freelistPages > 0) {
+        info(`${stats.freelistPages} freed page(s) reclaimable — abx serve does this automatically between watch ticks; ` +
+            `run one pass now with ${g('abx vacuum incremental')}`);
+    }
+    else {
+        ok('nothing to reclaim');
+    }
+}
+function cmdVacuumConvert() {
+    const store = requireSqliteStore();
+    const before = store.vacuumStats();
+    if (before.mode !== 'none') {
+        ok(`already converted — auto_vacuum is '${before.mode}'; nothing to do.`);
+        return;
+    }
+    console.log(`${bold('abx vacuum convert')} runs a full SQLite ${bold('VACUUM')} on ${store.path} to enable incremental ` +
+        `auto-vacuum.\n` +
+        `${dim(`this REWRITES THE ENTIRE FILE (currently ${before.pageCount} page(s)) and can briefly need up to`)}\n` +
+        `${dim('~2x its on-disk size while it runs. This is a one-time operation — after it, freed pages reclaim')}\n` +
+        `${dim(`incrementally instead (${g('abx vacuum incremental')}, or automatically between abx serve's watch ticks).`)}\n`);
+    console.log(`converting… (auto_vacuum: none → incremental)`);
+    const mode = store.vacuumConvert();
+    const after = store.vacuumStats();
+    ok(`done — auto_vacuum is now '${mode}'; ${before.pageCount} → ${after.pageCount} page(s).`);
+}
+function cmdVacuumIncremental(flags) {
+    const store = requireSqliteStore();
+    const maxPages = flags.pages !== undefined ? Number(flags.pages) : DEFAULT_INCREMENTAL_VACUUM_PAGES;
+    if (!Number.isFinite(maxPages) || maxPages <= 0) {
+        throw new Error(`--pages must be a positive number (got ${JSON.stringify(flags.pages)})`);
+    }
+    const mode = store.autoVacuumMode();
+    if (mode !== 'incremental') {
+        warn(`auto_vacuum is '${mode}' — incremental_vacuum has nothing to do until this store is converted: ${g('abx vacuum convert')}`);
+        return;
+    }
+    const reclaimed = store.runIncrementalVacuum(maxPages);
+    if (reclaimed > 0)
+        ok(`reclaimed ${reclaimed} page(s) (bounded to ${maxPages} this pass)`);
+    else
+        info('nothing to reclaim');
+}
+const VACUUM_USAGE = `usage: abx vacuum [status|convert|incremental] [--pages <n>]`;
+export const VACUUM_HELP = `
+  ${bold('abx vacuum')} [status|convert|incremental] ${dim('— SQLite maintenance for the local reference store; read-only unless a write happens below')}
+    ${g('abx vacuum')}              ${dim('(default: status)')} report auto_vacuum mode + page/freelist counts
+    ${g('abx vacuum convert')}      one-time, EXPLICIT full VACUUM for a store stuck at auto_vacuum='none' — rewrites
+                          the whole file; can briefly need up to ~2x its on-disk size. Never runs automatically.
+    ${g('abx vacuum incremental')} [--pages <n>]  one bounded PRAGMA incremental_vacuum pass (default ${DEFAULT_INCREMENTAL_VACUUM_PAGES}
+                          pages) — the same bounded reclaim \`abx serve\` already runs automatically BETWEEN watch
+                          ticks; use this on demand (after \`convert\`, or on a node not running \`abx serve\`).
+    ${dim('c.f. site/content/docs/using-abx/self-hosting.mdx → SQLite maintenance.')}`;
+//# sourceMappingURL=maintenance.js.map

package/dist/commands/maintenance.js.map

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