@pdpp/cli 0.1.0-beta.7 → 0.1.0

package/src/ref/commands/connectors.js

@@ -1,10 +1,10 @@
 import { parseArgs, requirePositional } from '../args.js';
 import { PdppUsageError } from '../errors.js';
 import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
-import { resolveFormat, writeData } from '../output.js';
+import { resolveFormat, writeData, writeEnvelopeWarnings } from '../output.js';
 
 // Operator-facing summary projection. Mirrors the evidence the dashboard renders
-// in `apps/web/src/app/dashboard/lib/ref-client.ts` (RefConnectorSummary +
+// in `apps/console/src/app/dashboard/lib/ref-client.ts` (RefConnectorSummary +
 // RefConnectionHealthSnapshot + RefNextAction). The reference server has
 // already redacted secret-bearing fields (e.g. `action_target` for
 // `sensitivity: "secret"` attention rows); we surface what arrives, with no
@@ -17,6 +17,7 @@ function projectSummaryRow(summary) {
   const schedule = summary?.schedule || null;
   const lastRun = summary?.last_run || null;
   const lastSuccess = summary?.last_successful_run || null;
+  const dominantCondition = findConditionById(health.conditions, health.dominant_condition_id);
   return {
     connection_id: summary?.connection_id ?? null,
     connector_id: summary?.connector_id ?? null,
@@ -29,6 +30,13 @@ function projectSummaryRow(summary) {
     syncing: badges.syncing === true,
     stale: badges.stale === true,
     reason_code: health.reason_code ?? null,
+    dominant_condition_id: health.dominant_condition_id ?? null,
+    dominant_condition_type: dominantCondition?.type ?? null,
+    dominant_condition_reason: dominantCondition?.reason ?? null,
+    dominant_condition_severity: dominantCondition?.severity ?? null,
+    dominant_condition_message: dominantCondition?.message ?? null,
+    dominant_condition_origin: dominantCondition?.origin ?? null,
+    supporting_condition_ids: Array.isArray(health.supporting_condition_ids) ? health.supporting_condition_ids : [],
     unknown_reasons: Array.isArray(health.unknown_reasons) ? health.unknown_reasons : [],
     next_action_source: nextAction?.source ?? 'none',
     next_action_reason: nextAction?.reason_code ?? null,
@@ -42,10 +50,18 @@ function projectSummaryRow(summary) {
   };
 }
 
+function findConditionById(conditions, id) {
+  if (!id || !Array.isArray(conditions)) {
+    return null;
+  }
+  return conditions.find((condition) => condition?.id === id) || null;
+}
+
 export async function runRefConnectors(argv, io = {}, fetchImpl = globalThis.fetch) {
   const [subcommand, ...rest] = argv;
   const { flags, positionals } = parseArgs(rest);
   const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
 
   if (subcommand === 'list') {
     const asUrl = resolveReferenceUrl(flags);
@@ -60,10 +76,12 @@ export async function runRefConnectors(argv, io = {}, fetchImpl = globalThis.fet
     const verbose = flags.verbose === true || flags.verbose === 'true';
     if (verbose) {
       writeData(format === 'table' ? (body.data || []) : body, format, out);
+      writeEnvelopeWarnings(body, err);
       return 0;
     }
     const rows = Array.isArray(body?.data) ? body.data.map(projectSummaryRow) : [];
-    writeData(format === 'table' ? rows : { object: 'list', data: rows }, format, out);
+    writeData(format === 'table' ? rows.map(projectSummaryTableRow) : { object: 'list', data: rows }, format, out);
+    writeEnvelopeWarnings(body, err);
     return 0;
   }
 
@@ -81,10 +99,12 @@ export async function runRefConnectors(argv, io = {}, fetchImpl = globalThis.fet
     const verbose = flags.verbose === true || flags.verbose === 'true';
     if (verbose) {
       writeData(body, format, out);
+      writeEnvelopeWarnings(body, err);
       return 0;
     }
     const row = projectSummaryRow(body);
-    writeData(format === 'table' ? [row] : row, format, out);
+    writeData(format === 'table' ? [projectSummaryTableRow(row)] : row, format, out);
+    writeEnvelopeWarnings(body, err);
     return 0;
   }
 
@@ -92,3 +112,23 @@ export async function runRefConnectors(argv, io = {}, fetchImpl = globalThis.fet
     'Usage: pdpp ref connectors <list|show <connector-id>> [--as-url <url>] [--owner-session <cookie>] [--format json|table] [--verbose]'
   );
 }
+
+function projectSummaryTableRow(row) {
+  return {
+    connection_id: row.connection_id,
+    connector_id: row.connector_id,
+    display_name: row.display_name,
+    state: row.state,
+    coverage: row.coverage,
+    freshness: row.freshness,
+    attention: row.attention,
+    outbox: row.outbox,
+    syncing: row.syncing,
+    stale: row.stale,
+    reason_code: row.reason_code,
+    dominant_condition_reason: row.dominant_condition_reason,
+    next_action_reason: row.next_action_reason,
+    last_success_at: row.last_success_at,
+    next_attempt_at: row.next_attempt_at,
+  };
+}

package/src/ref/commands/event-subscriptions.js

@@ -0,0 +1,190 @@
+/**
+ * `pdpp ref event-subscriptions` — operator oversight of client event
+ * subscriptions. Mirrors the `_ref/event-subscriptions*` HTTP routes
+ * one-to-one. Owner-session-only; the CLI never sends or receives
+ * subscription secret material because the `_ref` projection strips it.
+ *
+ * Spec: openspec/changes/add-client-event-subscription-management/specs/
+ *       reference-implementation-architecture/spec.md
+ */
+
+import { parseArgs, requirePositional } from '../args.js';
+import { PdppCliError, PdppUsageError } from '../errors.js';
+import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
+import { resolveFormat, writeData, writeEnvelopeWarnings } from '../output.js';
+
+function projectListRow(row) {
+  return {
+    subscription_id: row.subscription_id,
+    authority: row.authority_kind || 'client_grant',
+    client_id: row.client_id,
+    grant_id: row.grant_id || '',
+    status: row.status,
+    callback_host: row.callback_host,
+    disabled_reason: row.disabled_reason ?? '',
+    pending: row.pending_queue_count ?? 0,
+    final_failures: row.final_failure_count ?? 0,
+    last_attempt_at: row.last_attempted_at ?? '',
+    last_attempt_ok: row.last_attempt_ok === null || row.last_attempt_ok === undefined ? '' : row.last_attempt_ok ? 'ok' : 'fail',
+    last_attempt_code: row.last_attempt_status_code ?? '',
+    updated_at: row.updated_at,
+  };
+}
+
+function projectDetail(detail) {
+  return {
+    subscription_id: detail.subscription_id,
+    authority: detail.authority_kind || 'client_grant',
+    client_id: detail.client_id,
+    grant_id: detail.grant_id || '',
+    status: detail.status,
+    disabled_reason: detail.disabled_reason ?? '',
+    callback_url: detail.callback_url,
+    created_at: detail.created_at,
+    updated_at: detail.updated_at,
+    disabled_at: detail.disabled_at ?? '',
+    pending_queue_count: detail.pending_queue_count,
+    final_failure_count: detail.final_failure_count,
+    last_attempt_at: detail.last_attempted_at ?? '',
+    last_attempt_ok: detail.last_attempt_ok ?? '',
+    last_attempt_code: detail.last_attempt_status_code ?? '',
+    recent_attempts: (detail.recent_attempts || []).length,
+  };
+}
+
+async function readConfirmation(io) {
+  const stdin = io.stdin || process.stdin;
+  if (!stdin || stdin.isTTY === false) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    let buf = '';
+    const onData = (chunk) => {
+      buf += chunk;
+      const newlineIdx = buf.indexOf('\n');
+      if (newlineIdx !== -1) {
+        stdin.removeListener('data', onData);
+        if (typeof stdin.setRawMode === 'function') {
+          try { stdin.setRawMode(false); } catch { /* ignore */ }
+        }
+        try { stdin.pause(); } catch { /* ignore */ }
+        resolve(buf.slice(0, newlineIdx).trim());
+      }
+    };
+    try { stdin.setEncoding('utf8'); } catch { /* ignore */ }
+    stdin.on('data', onData);
+    try { stdin.resume(); } catch { /* ignore */ }
+  });
+}
+
+export async function runRefEventSubscriptions(argv, io = {}, fetchImpl = globalThis.fetch) {
+  const [subcommand, ...rest] = argv;
+  const { flags, positionals } = parseArgs(rest);
+  const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
+
+  if (subcommand === 'list') {
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const query = new URLSearchParams();
+    if (flags['client-id']) query.set('client_id', String(flags['client-id']));
+    if (flags['grant-id']) query.set('grant_id', String(flags['grant-id']));
+    if (flags.status) query.set('status', String(flags.status));
+    const queryString = query.toString();
+    const url = `${asUrl}/_ref/event-subscriptions${queryString ? `?${queryString}` : ''}`;
+    const { body } = await fetchJson(
+      url,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl,
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    const rows = body?.data || [];
+    if (format === 'table') {
+      writeData(rows.map(projectListRow), 'table', out);
+    } else {
+      writeData(body, format, out);
+    }
+    writeEnvelopeWarnings(body, err);
+    return 0;
+  }
+
+  if (subcommand === 'show') {
+    const subscriptionId = requirePositional(positionals, 0, 'subscription-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/event-subscriptions/${encodeURIComponent(subscriptionId)}`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl,
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    if (format === 'table') {
+      writeData(projectDetail(body), 'table', out);
+    } else {
+      writeData(body, format, out);
+    }
+    writeEnvelopeWarnings(body, err);
+    return 0;
+  }
+
+  if (subcommand === 'disable') {
+    const subscriptionId = requirePositional(positionals, 0, 'subscription-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const reason = typeof flags.reason === 'string' ? flags.reason : null;
+    const explicitYes = flags.yes === true || flags.yes === 'true';
+
+    if (!explicitYes) {
+      const headers = { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) };
+      const { body } = await fetchJson(
+        `${asUrl}/_ref/event-subscriptions/${encodeURIComponent(subscriptionId)}`,
+        { headers },
+        fetchImpl,
+      );
+      const authority = body.authority_kind || 'client_grant';
+      const grant = body.grant_id || 'none';
+      err.write(`Subscription ${body.subscription_id} (authority=${authority}, client=${body.client_id}, grant=${grant}, status=${body.status})\n`);
+      err.write(`Callback: ${body.callback_url}\n`);
+      err.write(`Disable subscription? Type 'yes' to confirm: `);
+      const answer = await readConfirmation(io);
+      if (!answer || answer.toLowerCase() !== 'yes') {
+        err.write('Aborted.\n');
+        return 1;
+      }
+    }
+
+    const body = reason ? { reason } : {};
+    const { body: detail } = await fetchJson(
+      `${asUrl}/_ref/event-subscriptions/${encodeURIComponent(subscriptionId)}/disable`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }),
+        },
+        body: JSON.stringify(body),
+      },
+      fetchImpl,
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    if (format === 'table') {
+      writeData(projectDetail(detail), 'table', out);
+    } else {
+      writeData(detail, format, out);
+    }
+    return 0;
+  }
+
+  throw new PdppUsageError(
+    'Usage:\n' +
+    '  pdpp ref event-subscriptions list [--client-id <id>] [--grant-id <id>] [--status <status>] [--as-url <url>] [--owner-session <cookie>] [--format json|table]\n' +
+    '  pdpp ref event-subscriptions show <subscription-id> [--as-url <url>] [--owner-session <cookie>] [--format json|table]\n' +
+    '  pdpp ref event-subscriptions disable <subscription-id> [--reason <text>] [--yes] [--as-url <url>] [--owner-session <cookie>]'
+  );
+}
+
+// Re-export for shaped error surface in case the CLI dispatcher needs it.
+export { PdppCliError };

package/src/ref/commands/grant.js

@@ -1,12 +1,13 @@
 import { parseArgs, requirePositional } from '../args.js';
 import { PdppUsageError } from '../errors.js';
 import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
-import { resolveFormat, writeData } from '../output.js';
+import { resolveFormat, writeData, writeEnvelopeWarnings } from '../output.js';
 
 export async function runRefGrant(argv, io = {}, fetchImpl = globalThis.fetch) {
   const [subcommand, ...rest] = argv;
   const { flags, positionals } = parseArgs(rest);
   const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
 
   if (subcommand === 'timeline') {
     const grantId = requirePositional(positionals, 0, 'grant-id');
@@ -20,6 +21,7 @@ export async function runRefGrant(argv, io = {}, fetchImpl = globalThis.fetch) {
     );
     const format = resolveFormat(flags, 'table', 'json');
     writeData(format === 'table' ? (body.data || []) : body, format, out);
+    writeEnvelopeWarnings(body, err);
     return 0;
   }
 

package/src/ref/commands/run.js

@@ -1,12 +1,13 @@
 import { parseArgs, requirePositional } from '../args.js';
 import { PdppUsageError } from '../errors.js';
 import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
-import { resolveFormat, writeData } from '../output.js';
+import { resolveFormat, writeData, writeEnvelopeWarnings } from '../output.js';
 
 export async function runRefRun(argv, io = {}, fetchImpl = globalThis.fetch) {
   const [subcommand, ...rest] = argv;
   const { flags, positionals } = parseArgs(rest);
   const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
 
   if (subcommand === 'timeline') {
     const runId = requirePositional(positionals, 0, 'run-id');
@@ -20,6 +21,7 @@ export async function runRefRun(argv, io = {}, fetchImpl = globalThis.fetch) {
     );
     const format = resolveFormat(flags, 'table', 'json');
     writeData(format === 'table' ? (body.data || []) : body, format, out);
+    writeEnvelopeWarnings(body, err);
     return 0;
   }
 

package/src/ref/commands/trace.js

@@ -1,12 +1,13 @@
 import { parseArgs, requirePositional } from '../args.js';
 import { PdppUsageError } from '../errors.js';
 import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
-import { resolveFormat, writeData } from '../output.js';
+import { resolveFormat, writeData, writeEnvelopeWarnings } from '../output.js';
 
 export async function runRefTrace(argv, io = {}, fetchImpl = globalThis.fetch) {
   const [subcommand, ...rest] = argv;
   const { flags, positionals } = parseArgs(rest);
   const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
 
   if (subcommand === 'show') {
     const traceId = requirePositional(positionals, 0, 'trace-id');
@@ -20,6 +21,7 @@ export async function runRefTrace(argv, io = {}, fetchImpl = globalThis.fetch) {
     );
     const format = resolveFormat(flags, 'table', 'json');
     writeData(format === 'table' ? (body.data || []) : body, format, out);
+    writeEnvelopeWarnings(body, err);
     return 0;
   }
 

package/src/ref/output.js

@@ -2,6 +2,50 @@ export function resolveFormat(flags, defaultWhenTty = 'json', defaultWhenPipe =
   return flags.format || (process.stdout.isTTY ? defaultWhenTty : defaultWhenPipe);
 }
 
+/**
+ * Extract the canonical `meta.warnings` array from a public read response
+ * body. Returns `[]` when the field is missing or malformed. The canonical
+ * envelope (canonicalize-public-read-contract) puts non-fatal lossiness,
+ * deprecated alias use, and count downgrades here; the CLI must surface
+ * them so operators are not silently misled by a lossy read. Pre-canonical
+ * responses have no `meta.warnings`, so this returns an empty array and
+ * the renderer prints nothing.
+ */
+export function extractEnvelopeWarnings(body) {
+  if (!body || typeof body !== 'object') {
+    return [];
+  }
+  const meta = body.meta;
+  if (!meta || typeof meta !== 'object') {
+    return [];
+  }
+  const warnings = Array.isArray(meta.warnings) ? meta.warnings : [];
+  return warnings.filter((w) => w && typeof w === 'object' && typeof w.code === 'string');
+}
+
+/**
+ * Write canonical `meta.warnings` to stderr in a human-readable form.
+ * Stays on stderr so machine-readable stdout (JSON, JSONL, table) is not
+ * polluted; operators piping to jq/grep keep their parseable output and
+ * still see the warning.
+ */
+export function writeEnvelopeWarnings(body, err = process.stderr) {
+  const warnings = extractEnvelopeWarnings(body);
+  if (warnings.length === 0) {
+    return;
+  }
+  for (const warning of warnings) {
+    const parts = [`warning: ${warning.code}`];
+    if (warning.message) {
+      parts.push(warning.message);
+    }
+    if (warning.dropped_parameter) {
+      parts.push(`(dropped: ${warning.dropped_parameter})`);
+    }
+    err.write(`${parts.join(' — ')}\n`);
+  }
+}
+
 export function writeData(data, format = 'json', out = process.stdout) {
   if (format === 'json') {
     out.write(`${JSON.stringify(data, null, 2)}\n`);