quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/entity.js

@@ -0,0 +1,119 @@
+/**
+ * Entity commands: CRUD, search, relate
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerEntityCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const entity = program
+    .command('entity')
+    .description('Manage entities in the knowledge graph');
+
+  entity
+    .command('list')
+    .description('List entities')
+    .option('--type <type>', 'filter by type')
+    .option('--limit <n>', 'max results', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = { limit: options.limit };
+      if (options.type) query.type = options.type;
+      const data = await client.get(resolveEndpoint('entity.list').path, { service: resolveEndpoint('entity.list').service, query });
+      formatOutput({
+        // fleet #392: entities has entity_type/first_seen, not type/created_at.
+        columns: ['id', 'entity_type', 'name', 'first_seen'],
+        headers: ['ID', 'Type', 'Name', 'First Seen'],
+        rows: data.entities || data,
+      }, { format: program.opts().output });
+    });
+
+  entity
+    .command('get')
+    .description('Get entity details')
+    .argument('<id>', 'entity ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('entity.get', { id }).path, { service: resolveEndpoint('entity.get', { id }).service });
+      formatDetail(data.entity || data, { format: program.opts().output });
+    });
+
+  entity
+    .command('create')
+    .description('Create an entity')
+    .requiredOption('--type <type>', 'entity type')
+    .requiredOption('--name <name>', 'entity name')
+    .option('--metadata <json>', 'metadata as JSON')
+    .action(async (options) => {
+      auth.requireAuth();
+      const body = { type: options.type, name: options.name };
+      if (options.metadata) body.metadata = parseJSON(options.metadata, '--metadata');
+      await client.post(resolveEndpoint('entity.create').path, { service: resolveEndpoint('entity.create').service, body });
+      printSuccess(`Entity "${options.name}" created.`);
+    });
+
+  entity
+    .command('delete')
+    .description('Delete an entity, soft by default (also removes its relations)')
+    .argument('<id>', 'entity ID')
+    .option('--hard', 'permanently delete, no soft-delete')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.hard) query.hard = 'true';
+      await client.delete(resolveEndpoint('entity.delete', { id }).path, { service: resolveEndpoint('entity.delete', { id }).service, query });
+      printSuccess('Entity deleted.');
+    });
+
+  entity
+    .command('search')
+    .description('Search entities')
+    .requiredOption('--query <q>', 'search query')
+    .option('--type <type>', 'filter by type')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = { query: options.query };
+      if (options.type) query.type = options.type;
+      const data = await client.get(resolveEndpoint('entity.search.list').path, { service: resolveEndpoint('entity.search.list').service, query });
+      formatOutput({
+        // fleet #392: search returns entity_type and bm25(...) AS rank.
+        columns: ['id', 'entity_type', 'name', 'rank'],
+        headers: ['ID', 'Type', 'Name', 'Rank'],
+        rows: data.entities || data.results || data,
+      }, { format: program.opts().output });
+    });
+
+  entity
+    .command('relate')
+    .description('Create a relation between entities')
+    .argument('<fromId>', 'source entity ID')
+    .argument('<toId>', 'target entity ID')
+    .requiredOption('--type <relType>', 'relation type')
+    .action(async (fromId, toId, options) => {
+      auth.requireAuth();
+      await client.post(resolveEndpoint('entity.relation').path, {
+        service: resolveEndpoint('entity.relation').service,
+        body: { from_id: fromId, to_id: toId, type: options.type },
+      });
+      printSuccess('Relation created.');
+    });
+
+  entity
+    .command('unrelate')
+    .description('Delete a relation between entities, soft by default')
+    .argument('<relationId>', 'relation ID')
+    .option('--hard', 'permanently delete, no soft-delete')
+    .action(async (relationId, options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.hard) query.hard = 'true';
+      await client.delete(resolveEndpoint('entity.relation.delete', { id: relationId }).path, {
+        service: resolveEndpoint('entity.relation.delete', { id: relationId }).service,
+        query,
+      });
+      printSuccess('Relation deleted.');
+    });
+}

package/lib/commands/facebook.js

@@ -0,0 +1,212 @@
+/**
+ * `quox facebook` — Facebook Pages plugin verbs, FB-3 (linkedin CLI parity).
+ *
+ * quox facebook post "<message>" --page <page_id> [--link <url>] [--image <https url>]
+ * quox facebook pages [--limit <n>]
+ * quox facebook posts --page <page_id> [--limit <n>]
+ * quox facebook insights --page <page_id> [--metrics <a,b,c>] [--period <period>]
+ * quox facebook lead-forms --page <page_id>
+ * quox facebook leads --form <form_id>
+ *
+ * The write verb executes the facebook_pages connector tool through the
+ * governed collector endpoint (POST /api/v1/tools/execute -> connector
+ * bridge). The bridge gates it on requiresApproval: it files an owner
+ * approval card and returns immediately with
+ * { pending:true, status:'awaiting_approval', approvalId, inbox_item_id }.
+ * The actual Facebook Graph API write only happens once the owner approves
+ * via the dashboard inbox or `quox inbox respond <id> --action approve`.
+ * Reads (pages, posts, insights, lead-forms, leads) execute directly.
+ *
+ * Pages are addressed by numeric Page ID by design: the CLI has no
+ * org-scoped default-page lookup yet, so --page/--form are required on
+ * every verb rather than silently guessed.
+ */
+
+import { formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+/**
+ * Execute one facebook_pages connector tool via the governed collector
+ * endpoint. A pending-approval response is a SUCCESS shape here (the card
+ * was filed); only a non-pending success:false is an error.
+ */
+async function executeFacebookTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing publishes until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerFacebookCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const facebook = program
+    .command('facebook')
+    .description('Facebook Pages publishing (organic): governed, HITL-approved via HITL Inbox');
+
+  // ── facebook post ────────────────────────────────────────────────────────
+
+  facebook
+    .command('post')
+    .description('Draft a Facebook Page post. Files an owner approval card and returns immediately; never posts directly.')
+    .argument('<message>', 'post text')
+    .requiredOption('--page <page_id>', 'Facebook Page ID to post to')
+    .option('--link <url>', 'attach a link URL')
+    .option('--image <url>', 'attach an image from an https URL; the Graph API fetches it server-side')
+    .action(async (message, options) => {
+      const input = { page_id: options.page, message };
+      if (options.link) input.link = options.link;
+      if (options.image) input.image_url = options.image;
+
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_publish_page_post', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Post', data);
+    });
+
+  // ── facebook pages (read) ────────────────────────────────────────────────
+
+  facebook
+    .command('pages')
+    .description('List the Facebook Pages this token can manage (read-only, no approval needed).')
+    .option('--limit <n>', 'max pages to return (max 100)', '25')
+    .action(async (options) => {
+      const limit = Math.min(parseInt(options.limit, 10) || 25, 100);
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_get_pages', { limit });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const pages = data.result || [];
+      if (pages.length === 0) {
+        printInfo('No pages returned.');
+        return;
+      }
+      for (const p of pages) {
+        console.log(`${p.id}  ${p.name}  ${p.category || ''}  followers:${p.followers ?? 'unknown'}`);
+      }
+    });
+
+  // ── facebook posts (read) ────────────────────────────────────────────────
+
+  facebook
+    .command('posts')
+    .description('List recent posts on a Facebook Page (read-only, no approval needed).')
+    .requiredOption('--page <page_id>', 'Facebook Page ID')
+    .option('--limit <n>', 'number of posts (max 50)', '10')
+    .action(async (options) => {
+      const limit = Math.min(parseInt(options.limit, 10) || 10, 50);
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_get_page_posts', {
+        page_id: options.page,
+        limit,
+      });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const posts = data.result || [];
+      if (posts.length === 0) {
+        printInfo('No posts returned.');
+        return;
+      }
+      for (const p of posts) {
+        console.log(`${p.id}  ${p.created_time || ''}`);
+        console.log(`  ${String(p.message || '').replace(/\n/g, '\n  ')}`);
+      }
+    });
+
+  // ── facebook insights (read) ─────────────────────────────────────────────
+
+  facebook
+    .command('insights')
+    .description('Show organic Page Insights (impressions, engagement, fans) for a Facebook Page.')
+    .requiredOption('--page <page_id>', 'Facebook Page ID')
+    .option('--metrics <metrics>', 'comma-separated metric names')
+    .option('--period <period>', 'day|week|days_28|month|lifetime')
+    .action(async (options) => {
+      const input = { page_id: options.page };
+      if (options.metrics) input.metrics = options.metrics;
+      if (options.period) input.period = options.period;
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_get_page_insights', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const series = data.result || [];
+      if (series.length === 0) {
+        printInfo('No insights returned.');
+        return;
+      }
+      for (const m of series) {
+        const latest = (m.values || [])[m.values.length - 1];
+        console.log(`${m.title || m.name}: ${latest ? JSON.stringify(latest.value) : 'unknown'}`);
+      }
+    });
+
+  // ── facebook lead-forms (read) ───────────────────────────────────────────
+
+  facebook
+    .command('lead-forms')
+    .description('List the Lead Ads forms attached to a Facebook Page.')
+    .requiredOption('--page <page_id>', 'Facebook Page ID')
+    .action(async (options) => {
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_get_lead_forms', { page_id: options.page });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const forms = data.result || [];
+      if (forms.length === 0) {
+        printInfo('No lead forms returned.');
+        return;
+      }
+      for (const f of forms) {
+        console.log(`${f.id}  ${f.name}  status:${f.status || 'unknown'}  leads:${f.leads_count ?? 'unknown'}`);
+      }
+    });
+
+  // ── facebook leads (read) ────────────────────────────────────────────────
+
+  facebook
+    .command('leads')
+    .description('Retrieve submitted leads for a Lead Ads form.')
+    .requiredOption('--form <form_id>', 'Lead form ID (from lead-forms)')
+    .action(async (options) => {
+      const data = await executeFacebookTool({ client, auth, program }, 'facebook_pages_get_leads', { form_id: options.form });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const leads = data.result || [];
+      if (leads.length === 0) {
+        printInfo('No leads returned.');
+        return;
+      }
+      for (const l of leads) {
+        console.log(`${l.id}  ${l.created_time || ''}`);
+        console.log(`  ${JSON.stringify(l.fields || {})}`);
+      }
+    });
+}

package/lib/commands/fetchAllowlist.js

@@ -0,0 +1,71 @@
+/**
+ * `quox fetch allow` — the URL prefixes this org's agents may GET through the
+ * governed web_fetch_allowlisted tool (quox#1171). Default-deny: nothing is
+ * fetchable until an org admin adds a prefix. Every call goes through the
+ * collector; adding and removing need a human org admin (the server refuses
+ * agent tokens).
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+
+async function call(client, id, params = {}, body) {
+  const ep = resolveEndpoint(id, params);
+  const opts = { service: ep.service };
+  if (body) opts.body = body;
+  switch (ep.method) {
+    case 'POST': return client.post(ep.path, opts);
+    case 'DELETE': return client.delete(ep.path, opts);
+    default: return client.get(ep.path, opts);
+  }
+}
+
+export function registerFetchAllowlistCommands(program, ctx) {
+  const { client } = ctx;
+
+  const f = program
+    .command('fetch')
+    .description('Governed agent fetch: which URLs your agents may GET');
+
+  const al = f.command('allow')
+    .description('The URL prefixes this org allows agents to fetch (default-deny)');
+
+  al.command('list', { isDefault: true })
+    .description('Show the allowed URL prefixes for this org')
+    .action(async () => {
+      const d = await call(client, 'fetchAllowlist.list');
+      if (d.prefixes?.length) {
+        process.stdout.write('allowed prefixes:\n');
+        for (const e of d.prefixes) process.stdout.write(`  ${e.url_prefix}${e.note ? `  (${e.note})` : ''}\n`);
+      } else {
+        process.stdout.write('none allowed yet: agents cannot fetch anything. Add one with `quox fetch allow add <url-prefix>`\n');
+      }
+    });
+
+  al.command('add <url-prefix>')
+    .description('Allow agents to GET URLs under a prefix, e.g. https://status.example.com/api/')
+    .option('--note <text>', 'why it is allowed, shown alongside it later')
+    .action(async (urlPrefix, opts) => {
+      try {
+        const d = await call(client, 'fetchAllowlist.add', {}, { url_prefix: urlPrefix, note: opts.note });
+        process.stdout.write(`allowed ${d.entry.url_prefix}\n`);
+        process.stdout.write(`  ${d.prefixes.length} prefix(es) now allowed for this org\n`);
+      } catch (err) {
+        if (err?.status === 400 && err?.message) {
+          process.stderr.write(`Not added: ${err.message}\n`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    });
+
+  al.command('remove <url-prefix>')
+    .description('Stop allowing a URL prefix')
+    .action(async (urlPrefix) => {
+      const d = await call(client, 'fetchAllowlist.remove', { prefix: urlPrefix });
+      if (d.removed) process.stdout.write(`removed ${urlPrefix}\n`);
+      else process.stdout.write(`nothing to remove: ${urlPrefix} was not allowed for this org\n`);
+    });
+}
+
+export default registerFetchAllowlistCommands;

package/lib/commands/file.js

@@ -0,0 +1,165 @@
+/**
+ * File commands: upload, download, list, delete
+ */
+
+import { createWriteStream, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerFileCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const file = program
+    .command('file')
+    .description('Manage files');
+
+  file
+    .command('list')
+    .description('List files')
+    .action(async () => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('files.list').path, { service: resolveEndpoint('files.list').service });
+      formatOutput({
+        columns: ['id', 'name', 'size', 'type', 'created_at'],
+        headers: ['ID', 'Name', 'Size', 'Type', 'Created'],
+        rows: data.files || data,
+      }, { format: program.opts().output });
+    });
+
+  file
+    .command('upload')
+    .description('Upload a file')
+    .argument('<path>', 'local file path')
+    .option('--name <name>', 'override filename')
+    .action(async (filePath, options) => {
+      auth.requireAuth();
+      // fleet #381: node:buffer exports Blob but has NEVER exported
+      // FormData (it's a global from undici on Node >= 18). Destructuring
+      // it here yielded undefined and shadowed the working global, so
+      // `new FormData()` threw "FormData is not a constructor" — this
+      // command had never once worked.
+      const { Blob } = await import('node:buffer');
+      const { readFile } = await import('node:fs/promises');
+
+      const content = await readFile(filePath);
+      const fileName = options.name || basename(filePath);
+
+      const formData = new FormData();
+      // Field name must be 'files' (plural): the files service parses with
+      // multer's `upload.array('files', 100)`. Sending 'file' leaves
+      // req.files undefined, and the route's `for (const file of req.files)`
+      // then throws — measured against the live service as a 500 with zero
+      // files stored, vs 200 + 1 stored for 'files'. So this is a genuine
+      // second bug: fixing the FormData crash alone would have swapped a
+      // client-side crash for a server-side 500, still with no upload.
+      formData.append('files', new Blob([content]), fileName);
+
+      const data = await client.post(resolveEndpoint('files.upload').path, {
+        service: resolveEndpoint('files.upload').service,
+        body: formData,
+        timeout: 120000,
+      });
+      // The route responds {success, files: [{id, originalName, ...}]}.
+      // Report the id the server actually stored, and refuse to claim
+      // success when it stored nothing — the old fallback to the local
+      // fileName would print "File uploaded" for an empty result set.
+      const uploaded = data.files?.[0];
+      if (!uploaded?.id) {
+        throw new Error(`Upload failed: server accepted the request but stored no file (got: ${JSON.stringify(data).slice(0, 120)})`);
+      }
+      printSuccess(`File uploaded: ${uploaded.id}${uploaded.originalName ? ` (${uploaded.originalName})` : ''}`);
+    });
+
+  file
+    .command('download')
+    .description('Download a file')
+    .argument('<fileId>', 'file ID')
+    // fleet #384: this used to be `--output <path>`, which collided with the
+    // global `-o, --output <format>` (table|json|csv|quiet) declared in
+    // bin/quox.js. Commander binds the value to the PARENT option, so the
+    // subcommand's options.output was always undefined and the file-write
+    // branch below was unreachable — every download fell through to stdout.
+    // Renamed rather than made clever: guessing whether an --output value is
+    // "a format" or "a path" is exactly the kind of heuristic that breaks
+    // later. --output never worked here, so nothing can depend on it.
+    .option('--dest <path>', 'write the file to this path (the global -o/--output sets output FORMAT, not a path)')
+    .action(async (fileId, options) => {
+      auth.requireAuth();
+      const res = await client.get(resolveEndpoint('file.get', { fileId }).path, { service: resolveEndpoint('file.get', { fileId }).service, raw: true });
+
+      if (!res.ok) {
+        throw new Error(`Download failed: ${res.status}`);
+      }
+
+      const { pipeline } = await import('node:stream/promises');
+
+      if (options.dest) {
+        const writer = createWriteStream(options.dest);
+        await pipeline(res.body, writer);
+        printSuccess(`Downloaded to ${options.dest}`);
+      } else {
+        // Stream the raw body. This used to be `res.text()`, which UTF-8
+        // decodes: any byte sequence that isn't valid UTF-8 became U+FFFD,
+        // so a piped binary came out corrupted AND larger than the original
+        // (measured 1.77x on a PNG). Piping the body preserves bytes exactly.
+        await pipeline(res.body, process.stdout);
+      }
+    });
+
+  file
+    .command('delete')
+    .description('Delete a file')
+    .argument('<fileId>', 'file ID')
+    .action(async (fileId) => {
+      auth.requireAuth();
+      await client.delete(resolveEndpoint('file.delete', { fileId }).path, { service: resolveEndpoint('file.delete', { fileId }).service });
+      printSuccess('File deleted.');
+    });
+
+  file
+    .command('stats')
+    .description('Show file storage stats')
+    .action(async () => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('files.stats').path, { service: resolveEndpoint('files.stats').service });
+      formatDetail(data.stats || data, { format: program.opts().output, title: 'File Storage Stats' });
+    });
+
+  // F01 A': legacy files with no proven owner are hidden from every org until a human instance admin assigns them.
+  file
+    .command('quarantine')
+    .description('List files with no proven owner org (instance admin only)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('files.quarantine.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      formatOutput({ columns: ['id', 'name', 'size'], headers: ['ID', 'Name', 'Size'], rows: data.files || [] }, { format: program.opts().output });
+    });
+
+  file
+    .command('assign')
+    .description('Assign a quarantined file to an org (instance admin only; witnessed): <fileId> --org <orgId>, or --from-report <dry-run.json>')
+    .argument('[fileId]', 'quarantined file id')
+    .option('--org <orgId>', 'org that owns the file')
+    .option('--from-report <path>', 'an owner-approved backfill dry-run report: assigns only rows with a derived owner')
+    .action(async (fileId, options) => {
+      auth.requireAuth();
+      let assignments;
+      if (options.fromReport) {
+        const report = JSON.parse(readFileSync(options.fromReport, 'utf8'));
+        assignments = (report.rows || []).filter((r) => r && r.id && r.orgId).map((r) => ({ file_id: r.id, org_id: r.orgId }));
+        if (!assignments.length) throw new Error('The report has no rows with a derived owner; nothing to assign.');
+      } else if (fileId) {
+        if (!options.org) throw new Error('Give the owning org: quox file assign <fileId> --org <orgId>');
+        assignments = [{ file_id: fileId, org_id: options.org }];
+      } else {
+        throw new Error('Give <fileId> --org <orgId>, or --from-report <dry-run.json>');
+      }
+      const ep = resolveEndpoint('files.quarantine.assign');
+      const data = await client.post(ep.path, { service: ep.service, body: { assignments } });
+      formatOutput({ columns: ['file_id', 'org_id', 'ok', 'error'], headers: ['File', 'Org', 'Assigned', 'Error'], rows: data.results || [] }, { format: program.opts().output });
+      const failed = (data.results || []).filter((r) => !r.ok).length;
+      if (failed) { process.exitCode = 1; } else { printSuccess(`Assigned ${assignments.length} file(s).`); }
+    });
+}