@pdpp/cli 0.1.0-beta.1 → 0.1.0-beta.3

package/src/index.js

@@ -3,7 +3,14 @@ import {
   getPdppCliPackageInfo,
   PDPP_CLI_BIN_NAME,
 } from './package-info.js';
-import { ConnectError, connectProvider, normalizeProviderUrl } from './connect/flow.js';
+import { ConnectError, connectProvider, normalizeProviderUrl, readStoredCredential } from './connect/flow.js';
+import { runCollector } from './collector/commands.js';
+import { runRefRun } from './ref/commands/run.js';
+import { runRefGrant } from './ref/commands/grant.js';
+import { runRefTrace } from './ref/commands/trace.js';
+import { runRefLogin } from './ref/commands/login.js';
+import { runRefConnectors } from './ref/commands/connectors.js';
+import { PdppCliError, PdppUsageError } from './ref/errors.js';
 
 const HELP = `PDPP CLI
 
@@ -11,12 +18,33 @@ Usage:
   ${PDPP_CLI_BIN_NAME} --help
   ${PDPP_CLI_BIN_NAME} package-info [--provider-url <url>]
   ${PDPP_CLI_BIN_NAME} connect <provider-url>
+  ${PDPP_CLI_BIN_NAME} token <provider-url>
 
 Agent access:
   ${createPdppCliCommand()}
 
+Local collector (pair a host you control with a reference deployment):
+  ${PDPP_CLI_BIN_NAME} collector advertise
+  ${PDPP_CLI_BIN_NAME} collector enroll --base-url <url> --code <code>
+  ${PDPP_CLI_BIN_NAME} collector run    --base-url <url> --connector <id> ...
+
+Reference diagnostics (reference server only):
+  ${PDPP_CLI_BIN_NAME} ref login <reference-url>
+  ${PDPP_CLI_BIN_NAME} ref run timeline <run-id> --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref grant timeline <grant-id> --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref trace show <trace-id> --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref connectors list --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref connectors show <connector-id> --as-url <url>
+
 Notes:
   Do not ask users for owner bearer tokens for routine delegated access.
+  "pdpp collector" is a thin @pdpp/cli shim. Install @pdpp/local-collector
+  once, or use "npx -y @pdpp/local-collector ..." directly, for filesystem
+  collectors like Claude Code and Codex.
+  "pdpp ref" commands require a running PDPP reference server and an owner session.
+  "pdpp ref login" caches an owner session in project-local .pdpp/ with mode 0600;
+  later "pdpp ref" commands use the cache when --owner-session and
+  PDPP_OWNER_SESSION_COOKIE are absent.
 `;
 
 export async function runCli(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
@@ -52,6 +80,79 @@ export async function runCli(argv, io = { stdout: process.stdout, stderr: proces
     }
   }
 
+  if (command === 'token') {
+    const providerUrl = readFirstPositional(rest);
+    if (!providerUrl) {
+      io.stderr.write('Usage: pdpp token <provider-url>\n');
+      return 64;
+    }
+
+    try {
+      const { credential } = await readStoredCredential(providerUrl, {
+        cacheRoot: readOption(rest, '--cache-root'),
+      });
+      io.stdout.write(`${credential.access_token}\n`);
+      return 0;
+    } catch (error) {
+      if (error instanceof ConnectError) {
+        io.stderr.write(`${error.message}\n`);
+        return error.exitCode;
+      }
+      throw error;
+    }
+  }
+
+  if (command === 'collector') {
+    return await runCollector(rest, io);
+  }
+
+  if (command === 'ref') {
+    const [refCommand, ...refRest] = rest;
+
+    if (!refCommand || refCommand === '--help' || refCommand === '-h') {
+      io.stdout.write(`Reference diagnostics (reference server only):\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref login <reference-url> [--password-stdin] [--cache-root <dir>]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref run timeline <run-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref grant timeline <grant-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref trace show <trace-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref connectors list --as-url <url> [--owner-session <cookie>] [--format json|table] [--verbose]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref connectors show <connector-id> --as-url <url> [--owner-session <cookie>] [--format json|table] [--verbose]\n`);
+      io.stdout.write(`\nNotes:\n`);
+      io.stdout.write(`  "ref login" prompts the reference server's owner-login route and caches the\n`);
+      io.stdout.write(`  resulting session in .pdpp/owner-sessions/ (mode 0600). The cookie value is\n`);
+      io.stdout.write(`  never printed. The password must come from --password-stdin or\n`);
+      io.stdout.write(`  PDPP_OWNER_PASSWORD; it is not accepted on the command line.\n`);
+      return 0;
+    }
+
+    const refDispatch = {
+      login: runRefLogin,
+      run: runRefRun,
+      grant: runRefGrant,
+      trace: runRefTrace,
+      connectors: runRefConnectors,
+    };
+    const handler = refDispatch[refCommand];
+    if (!handler) {
+      io.stderr.write(`Unknown ref command: ${refCommand}\n`);
+      return 64;
+    }
+
+    try {
+      return await handler(refRest, io);
+    } catch (error) {
+      if (error instanceof PdppUsageError) {
+        io.stderr.write(`${error.message}\n`);
+        return error.exitCode;
+      }
+      if (error instanceof PdppCliError) {
+        io.stderr.write(`${error.message}\n`);
+        return error.exitCode;
+      }
+      throw error;
+    }
+  }
+
   io.stderr.write(`Unknown command: ${command}\n\n${HELP}\n`);
   return 64;
 }
@@ -65,4 +166,16 @@ function readOption(argv, name) {
   return argv[index + 1];
 }
 
-export { connectProvider, normalizeProviderUrl };
+function readFirstPositional(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value.startsWith('--')) {
+      index += 1;
+      continue;
+    }
+    return value;
+  }
+  return undefined;
+}
+
+export { connectProvider, normalizeProviderUrl, readStoredCredential };

package/src/package-info.js

@@ -1,9 +1,5 @@
-import { readFileSync } from 'node:fs';
-
-const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-
-export const PDPP_CLI_PACKAGE_NAME = manifest.name;
-export const PDPP_CLI_BIN_NAME = Object.keys(manifest.bin)[0];
+export const PDPP_CLI_PACKAGE_NAME = '@pdpp/cli';
+export const PDPP_CLI_BIN_NAME = 'pdpp';
 export const PDPP_CLI_VERSION_POLICY = 'beta';
 export const PDPP_CLI_PACKAGE_SPECIFIER = `${PDPP_CLI_PACKAGE_NAME}@${PDPP_CLI_VERSION_POLICY}`;
 export const PDPP_CLI_DEFAULT_CLIENT_ID = 'pdpp_cli';

package/src/ref/args.js

@@ -0,0 +1,47 @@
+import { PdppUsageError } from './errors.js';
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split('=', 2);
+    if (!rawKey) {
+      throw new PdppUsageError('Invalid empty flag');
+    }
+
+    if (inlineValue !== undefined) {
+      flags[rawKey] = inlineValue;
+      continue;
+    }
+
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      flags[rawKey] = next;
+      i += 1;
+      continue;
+    }
+
+    flags[rawKey] = true;
+  }
+
+  return { flags, positionals };
+}
+
+export function requirePositional(positionals, index, name) {
+  const value = positionals[index];
+  if (!value) {
+    throw new PdppUsageError(`Missing required argument: ${name}`);
+  }
+  return value;
+}

package/src/ref/commands/connectors.js

@@ -0,0 +1,94 @@
+import { parseArgs, requirePositional } from '../args.js';
+import { PdppUsageError } from '../errors.js';
+import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
+import { resolveFormat, writeData } from '../output.js';
+
+// Operator-facing summary projection. Mirrors the evidence the dashboard renders
+// in `apps/web/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
+// inference.
+function projectSummaryRow(summary) {
+  const health = summary?.connection_health || {};
+  const axes = health.axes || {};
+  const badges = health.badges || {};
+  const nextAction = summary?.next_action || health.next_action || null;
+  const schedule = summary?.schedule || null;
+  const lastRun = summary?.last_run || null;
+  const lastSuccess = summary?.last_successful_run || null;
+  return {
+    connection_id: summary?.connection_id ?? null,
+    connector_id: summary?.connector_id ?? null,
+    display_name: summary?.display_name ?? null,
+    state: health.state ?? 'unknown',
+    coverage: axes.coverage ?? 'unknown',
+    freshness: axes.freshness ?? 'unknown',
+    attention: axes.attention ?? 'none',
+    outbox: axes.outbox ?? 'unknown',
+    syncing: badges.syncing === true,
+    stale: badges.stale === true,
+    reason_code: health.reason_code ?? null,
+    unknown_reasons: Array.isArray(health.unknown_reasons) ? health.unknown_reasons : [],
+    next_action_source: nextAction?.source ?? 'none',
+    next_action_reason: nextAction?.reason_code ?? null,
+    next_action_owner_action: nextAction?.owner_action ?? null,
+    next_action_target: nextAction?.action_target ?? null,
+    next_action_expires_at: nextAction?.expires_at ?? null,
+    last_run_at: lastRun?.last_at ?? null,
+    last_run_status: lastRun?.status ?? null,
+    last_success_at: health.last_success_at ?? lastSuccess?.last_at ?? null,
+    next_attempt_at: health.next_attempt_at ?? schedule?.next_due_at ?? 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;
+
+  if (subcommand === 'list') {
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/connectors`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    const verbose = flags.verbose === true || flags.verbose === 'true';
+    if (verbose) {
+      writeData(format === 'table' ? (body.data || []) : body, format, out);
+      return 0;
+    }
+    const rows = Array.isArray(body?.data) ? body.data.map(projectSummaryRow) : [];
+    writeData(format === 'table' ? rows : { object: 'list', data: rows }, format, out);
+    return 0;
+  }
+
+  if (subcommand === 'show') {
+    const connectorId = requirePositional(positionals, 0, 'connector-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/connectors/${encodeURIComponent(connectorId)}`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    const verbose = flags.verbose === true || flags.verbose === 'true';
+    if (verbose) {
+      writeData(body, format, out);
+      return 0;
+    }
+    const row = projectSummaryRow(body);
+    writeData(format === 'table' ? [row] : row, format, out);
+    return 0;
+  }
+
+  throw new PdppUsageError(
+    'Usage: pdpp ref connectors <list|show <connector-id>> [--as-url <url>] [--owner-session <cookie>] [--format json|table] [--verbose]'
+  );
+}

package/src/ref/commands/grant.js

@@ -0,0 +1,29 @@
+import { parseArgs, requirePositional } from '../args.js';
+import { PdppUsageError } from '../errors.js';
+import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
+import { resolveFormat, writeData } 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;
+
+  if (subcommand === 'timeline') {
+    const grantId = requirePositional(positionals, 0, 'grant-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/grants/${encodeURIComponent(grantId)}/timeline`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    writeData(format === 'table' ? (body.data || []) : body, format, out);
+    return 0;
+  }
+
+  throw new PdppUsageError(
+    'Usage: pdpp ref grant timeline <grant-id> [--as-url <url>] [--owner-session <cookie>] [--format json|table]'
+  );
+}

package/src/ref/commands/login.js

@@ -0,0 +1,167 @@
+import { parseArgs } from '../args.js';
+import { PdppCliError, PdppUsageError } from '../errors.js';
+import { OWNER_SESSION_COOKIE_NAME } from '../fetch.js';
+import {
+  extractCookieFromSetCookie,
+  getOwnerSessionPaths,
+  writeOwnerSession,
+} from '../session.js';
+
+// Owner-session login UX for `pdpp ref ...`.
+//
+// Usage:
+//   pdpp ref login <reference-url> [--password-stdin] [--cache-root <dir>]
+//
+// Password sources, in precedence order:
+//   1. --password-stdin   (reads first line of stdin; CI-friendly)
+//   2. PDPP_OWNER_PASSWORD env var
+// We intentionally do NOT accept the password on argv to avoid leaking it
+// into shell history, ps output, or logs.
+//
+// On success: persists the issued owner-session cookie to project-local
+// `.pdpp/owner-sessions/<host>.json` with mode 0600. Cookie value is never
+// printed.
+export async function runRefLogin(argv, io = {}, fetchImpl = globalThis.fetch) {
+  const out = io.stdout || process.stdout;
+
+  const { flags, positionals } = parseArgs(argv);
+  const referenceUrlRaw = positionals[0];
+  if (!referenceUrlRaw) {
+    throw new PdppUsageError(
+      'Usage: pdpp ref login <reference-url> [--password-stdin] [--cache-root <dir>]'
+    );
+  }
+  const referenceUrl = referenceUrlRaw.replace(/\/$/, '');
+
+  const password = await resolvePassword(flags, io);
+  if (!password) {
+    throw new PdppUsageError(
+      'Owner password required. Pipe it via `--password-stdin` or set PDPP_OWNER_PASSWORD. ' +
+        'The password is never accepted on the command line.'
+    );
+  }
+
+  const loginUrl = `${referenceUrl}/owner/login`;
+  let resp;
+  try {
+    resp = await fetchImpl(loginUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify({ password }),
+      redirect: 'manual',
+    });
+  } catch (e) {
+    throw new PdppCliError(`Network request to ${loginUrl} failed: ${e.message}`);
+  }
+
+  const status = resp.status;
+  // The reference server's POST /owner/login responds with a 302 redirect
+  // and Set-Cookie on success, or 401/403 on failure. Anything outside
+  // 200-399 means the login was rejected.
+  if (status >= 400) {
+    if (status === 401) {
+      throw new PdppCliError(
+        'Owner login rejected: incorrect password (HTTP 401).',
+        3
+      );
+    }
+    if (status === 403) {
+      throw new PdppCliError(
+        'Owner login rejected: CSRF/policy failure (HTTP 403).',
+        4
+      );
+    }
+    if (status === 404) {
+      throw new PdppCliError(
+        `Owner login route not found at ${loginUrl} (HTTP 404). Confirm the reference server URL.`,
+        5
+      );
+    }
+    throw new PdppCliError(`Owner login failed: HTTP ${status}.`);
+  }
+
+  const setCookie = readSetCookie(resp);
+  const cookieValue = extractCookieFromSetCookie(setCookie, OWNER_SESSION_COOKIE_NAME);
+  if (!cookieValue) {
+    throw new PdppCliError(
+      'Owner login succeeded but no owner-session cookie was returned. ' +
+        'Confirm that placeholder owner auth is enabled on the reference server.'
+    );
+  }
+
+  const cacheRoot = flags['cache-root'] || '.pdpp';
+  const file = writeOwnerSession({
+    referenceUrl,
+    cookie: `${OWNER_SESSION_COOKIE_NAME}=${cookieValue}`,
+    cacheRoot,
+  });
+
+  // Never print the cookie value. Confirm location only.
+  out.write(`Saved owner session for ${referenceUrl}\n`);
+  out.write(`  cache: ${file}\n`);
+  return 0;
+}
+
+async function resolvePassword(flags, io) {
+  if (flags['password-stdin']) {
+    return readFirstLine(io.stdin || process.stdin);
+  }
+  const fromEnv = process.env.PDPP_OWNER_PASSWORD;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) {
+    return fromEnv;
+  }
+  return null;
+}
+
+function readFirstLine(stream) {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    if (!stream || typeof stream.on !== 'function') {
+      resolve('');
+      return;
+    }
+    stream.setEncoding?.('utf8');
+    const onData = (chunk) => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl !== -1) {
+        cleanup();
+        resolve(buf.slice(0, nl).replace(/\r$/, ''));
+      }
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve(buf.replace(/\r?\n$/, ''));
+    };
+    const onError = (e) => {
+      cleanup();
+      reject(e);
+    };
+    function cleanup() {
+      stream.off?.('data', onData);
+      stream.off?.('end', onEnd);
+      stream.off?.('error', onError);
+    }
+    stream.on('data', onData);
+    stream.on('end', onEnd);
+    stream.on('error', onError);
+  });
+}
+
+function readSetCookie(resp) {
+  const headers = resp.headers;
+  if (!headers) return null;
+  if (typeof headers.getSetCookie === 'function') {
+    const arr = headers.getSetCookie();
+    if (arr && arr.length) return arr;
+  }
+  if (typeof headers.get === 'function') {
+    return headers.get('set-cookie') || headers.get('Set-Cookie');
+  }
+  return headers['set-cookie'] || headers['Set-Cookie'] || null;
+}
+
+export { getOwnerSessionPaths };

package/src/ref/commands/run.js

@@ -0,0 +1,29 @@
+import { parseArgs, requirePositional } from '../args.js';
+import { PdppUsageError } from '../errors.js';
+import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
+import { resolveFormat, writeData } 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;
+
+  if (subcommand === 'timeline') {
+    const runId = requirePositional(positionals, 0, 'run-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/runs/${encodeURIComponent(runId)}/timeline`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    writeData(format === 'table' ? (body.data || []) : body, format, out);
+    return 0;
+  }
+
+  throw new PdppUsageError(
+    'Usage: pdpp ref run timeline <run-id> [--as-url <url>] [--owner-session <cookie>] [--format json|table]'
+  );
+}

package/src/ref/commands/trace.js

@@ -0,0 +1,29 @@
+import { parseArgs, requirePositional } from '../args.js';
+import { PdppUsageError } from '../errors.js';
+import { fetchJson, ownerSessionHeaders, resolveReferenceUrl } from '../fetch.js';
+import { resolveFormat, writeData } 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;
+
+  if (subcommand === 'show') {
+    const traceId = requirePositional(positionals, 0, 'trace-id');
+    const asUrl = resolveReferenceUrl(flags);
+    const ownerSession = flags['owner-session'] || '';
+    const cacheRoot = flags['cache-root'];
+    const { body } = await fetchJson(
+      `${asUrl}/_ref/traces/${encodeURIComponent(traceId)}`,
+      { headers: { ...ownerSessionHeaders({ ownerSession, referenceUrl: asUrl, cacheRoot }) } },
+      fetchImpl
+    );
+    const format = resolveFormat(flags, 'table', 'json');
+    writeData(format === 'table' ? (body.data || []) : body, format, out);
+    return 0;
+  }
+
+  throw new PdppUsageError(
+    'Usage: pdpp ref trace show <trace-id> [--as-url <url>] [--owner-session <cookie>] [--format json|table]'
+  );
+}

package/src/ref/errors.js

@@ -0,0 +1,37 @@
+export class PdppCliError extends Error {
+  constructor(message, exitCode = 1, details = null) {
+    super(message);
+    this.name = 'PdppCliError';
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+export class PdppUsageError extends PdppCliError {
+  constructor(message, details = null) {
+    super(message, 2, details);
+    this.name = 'PdppUsageError';
+  }
+}
+
+export class PdppHttpError extends PdppCliError {
+  constructor(message, status, body = null, responseMetadata = null) {
+    super(message, exitCodeForStatus(status), {
+      status,
+      body,
+      ...(responseMetadata || {}),
+    });
+    this.name = 'PdppHttpError';
+    this.status = status;
+    this.body = body;
+    this.requestId = responseMetadata?.request_id || null;
+    this.referenceTraceId = responseMetadata?.reference_trace_id || null;
+  }
+}
+
+function exitCodeForStatus(status) {
+  if (status === 401) return 3;
+  if (status === 403) return 4;
+  if (status === 404) return 5;
+  return 1;
+}

package/src/ref/fetch.js

@@ -0,0 +1,75 @@
+import { PdppCliError, PdppHttpError } from './errors.js';
+import { readOwnerSession } from './session.js';
+
+export const OWNER_SESSION_COOKIE_NAME = 'pdpp_owner_session';
+
+export async function fetchJson(url, opts = {}, fetchImpl = globalThis.fetch) {
+  let resp;
+  try {
+    resp = await fetchImpl(url, opts);
+  } catch (error) {
+    throw new PdppCliError(`Network request failed: ${error.message}`);
+  }
+
+  const text = await resp.text();
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+
+  if (!resp.ok) {
+    const message =
+      body?.error_description ||
+      body?.error?.message ||
+      body?.message ||
+      `HTTP ${resp.status} ${resp.statusText}`;
+    throw new PdppHttpError(message, resp.status, body);
+  }
+
+  return { status: resp.status, body, headers: resp.headers };
+}
+
+// Resolves owner session cookie with precedence:
+//   1. opts.ownerSession (e.g. --owner-session flag)
+//   2. PDPP_OWNER_SESSION_COOKIE env var
+//   3. project-local cached session (when opts.referenceUrl is provided)
+// Returns headers object with Cookie set, or empty object if no session found.
+export function ownerSessionHeaders(opts = {}) {
+  const fromOpts = typeof opts.ownerSession === 'string' ? opts.ownerSession : '';
+  const fromEnv =
+    typeof process.env.PDPP_OWNER_SESSION_COOKIE === 'string'
+      ? process.env.PDPP_OWNER_SESSION_COOKIE
+      : '';
+
+  let value = (fromOpts || fromEnv).trim();
+
+  if (!value && opts.referenceUrl) {
+    const cached = readOwnerSession({
+      referenceUrl: opts.referenceUrl,
+      cacheRoot: opts.cacheRoot,
+    });
+    if (cached) value = cached.cookie;
+  }
+
+  if (!value) return {};
+  const cookie = value.includes('=') ? value : `${OWNER_SESSION_COOKIE_NAME}=${value}`;
+  return { Cookie: cookie };
+}
+
+// Resolves the reference base URL from --as-url flag or PDPP_AS_URL / AS_URL env vars.
+export function resolveReferenceUrl(flags) {
+  const url =
+    flags['as-url'] ||
+    process.env.PDPP_AS_URL ||
+    process.env.AS_URL;
+  if (!url) {
+    throw new PdppCliError(
+      'Missing reference server URL. Provide --as-url <url> or set PDPP_AS_URL.'
+    );
+  }
+  return url.replace(/\/$/, '');
+}