@pitcher/cli-scripts 2.20.1 → 3.0.0

package/dist/src/commands/login.js

@@ -0,0 +1,348 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { createInterface } from 'node:readline';
+import { Command } from 'commander';
+import { authHeaders } from '../core/target.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError, isCliError } from '../core/errors.js';
+import { emitEnvelope, log } from '../core/output.js';
+import { AUTH0_NATIVE_CLIENT_IDS, buildAuthorizeUrl, exchangeCode, fetchOrgConfig, isUpstreamError, normalizeDomain, } from '../core/pitcherAuth.js';
+import { decodeJwtPayload, deleteSession, listSessionDomains, readSession, selectDomain, sessionCredential, withDomainLock, writeSession, } from '../core/session.js';
+/** The loopback redirect registered on both Auth0 Native apps (`http://127.0.0.1:53682/callback`). */
+export const LOGIN_PORT = 53682;
+const LOGIN_TIMEOUT_MS = 300000;
+const b64url = (b) => b.toString('base64url');
+/**
+ * The URL-opening command per platform. Windows uses the URL handler directly: through `cmd /c start`,
+ * cmd.exe would split the unquoted URL at its first `&` and drop client_id, state and the PKCE challenge.
+ */
+export function browserCommand(url, platform) {
+    if (platform === 'darwin')
+        return ['open', [url]];
+    if (platform === 'win32')
+        return ['rundll32', ['url.dll,FileProtocolHandler', url]];
+    return ['xdg-open', [url]];
+}
+function defaultOpenBrowser(url) {
+    const [cmd, args] = browserCommand(url, process.platform);
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        // the URL is printed to stderr regardless
+    }
+}
+function defaultPrompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer);
+    }));
+}
+/** Equal byte length first: `timingSafeEqual` throws on unequal lengths. */
+function stateMatches(received, expected) {
+    const a = Buffer.from(received);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** `GET /api/v1/users/me/` with the bearer: proves the token works on Django and yields the email. */
+export async function fetchMe(domain, cred, doFetch) {
+    let res;
+    try {
+        res = await doFetch(`https://${domain}/api/v1/users/me/`, {
+            headers: { accept: 'application/json', ...authHeaders(cred) },
+            redirect: 'error',
+            signal: AbortSignal.timeout(10000),
+        });
+    }
+    catch {
+        throw createCliError('NETWORK', `could not reach ${domain}`);
+    }
+    if (res.status === 401 || res.status === 403)
+        throw createCliError('AUTH', `${domain} refused the session`);
+    if (!res.ok)
+        throw createCliError('NETWORK', `${domain} answered ${res.status} for users/me`);
+    const body = (await res.json().catch(() => ({})));
+    return { email: typeof body.email === 'string' ? body.email : undefined };
+}
+/** One-shot loopback listener on 127.0.0.1 ONLY (never 0.0.0.0). Resolves with the code or rejects AUTH. */
+function listenForCallback(port, state, timeoutMs, onListen) {
+    return new Promise((resolveListen, rejectListen) => {
+        let settle;
+        const result = new Promise((resolve, reject) => {
+            settle = { resolve, reject };
+        });
+        let done = false;
+        let timer;
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (req.method !== 'GET' || url.pathname !== '/callback' || done) {
+                res.writeHead(404, { 'content-type': 'text/plain' }).end('Not found');
+                return;
+            }
+            done = true;
+            res
+                .writeHead(200, {
+                'content-type': 'text/plain; charset=utf-8',
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+            })
+                .end('You can close this tab and return to the terminal.');
+            close();
+            const error = url.searchParams.get('error');
+            if (error) {
+                settle?.reject(createCliError('AUTH', `login failed: ${error.slice(0, 64)}`));
+                return;
+            }
+            if (!stateMatches(url.searchParams.get('state') ?? '', state)) {
+                settle?.reject(createCliError('AUTH', 'login failed: state mismatch'));
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (!code) {
+                settle?.reject(createCliError('AUTH', 'login failed: no authorization code'));
+                return;
+            }
+            settle?.resolve({ code });
+        });
+        const close = () => {
+            if (timer)
+                clearTimeout(timer);
+            server.closeAllConnections?.();
+            server.close();
+        };
+        server.once('error', (e) => {
+            rejectListen(e.code === 'EADDRINUSE'
+                ? createCliError('AUTH', `port ${port} is busy (another p login?)`)
+                : createCliError('AUTH', `could not listen on 127.0.0.1:${port}`));
+        });
+        server.listen(port, '127.0.0.1', () => {
+            const address = server.address();
+            onListen?.(address);
+            timer = setTimeout(() => {
+                if (done)
+                    return;
+                done = true;
+                close();
+                settle?.reject(createCliError('AUTH', 'login timed out'));
+            }, timeoutMs);
+            resolveListen({ redirectUri: `http://127.0.0.1:${address.port}/callback`, result, close });
+        });
+    });
+}
+export async function runLogin(opts, deps = {}) {
+    const env = deps.env ?? process.env;
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const now = deps.now ?? Date.now;
+    try {
+        // 1. domain
+        let input = opts.domain;
+        if (!input) {
+            if (!(deps.isTty ?? Boolean(process.stdin.isTTY && process.stderr.isTTY))) {
+                throw createCliError('VALIDATION', 'pass --domain (e.g. --domain acme.my.pitcher.com)');
+            }
+            input = await (deps.prompt ?? defaultPrompt)('Pitcher domain (e.g. acme.my.pitcher.com): ');
+        }
+        const n = normalizeDomain(input);
+        if (!n.ok)
+            throw createCliError('VALIDATION', n.error);
+        const domain = n.domain;
+        // 2-3. org-config → tenant → Native client id
+        let cfg;
+        try {
+            cfg = await fetchOrgConfig(domain, { fetch: doFetch });
+        }
+        catch (e) {
+            if (isUpstreamError(e))
+                throw createCliError('NETWORK', `could not reach ${domain} (${e.message})`);
+            throw e;
+        }
+        if (!cfg || !cfg.organization)
+            throw createCliError('AUTH', 'This organization has no MCP login configured');
+        const organization = cfg.organization;
+        const clientId = AUTH0_NATIVE_CLIENT_IDS[cfg.auth0Domain];
+        if (!clientId)
+            throw createCliError('AUTH', `Pitcher login is not enabled for ${cfg.auth0Domain} yet`);
+        // 4. PKCE + state
+        const verifier = b64url(randomBytes(32));
+        const codeChallenge = b64url(createHash('sha256').update(verifier).digest());
+        const state = b64url(randomBytes(32));
+        // 5-7. loopback listener, browser, callback
+        const listener = await listenForCallback(deps.port ?? LOGIN_PORT, state, deps.timeoutMs ?? LOGIN_TIMEOUT_MS, deps.onListen);
+        const authorizeUrl = buildAuthorizeUrl({
+            auth0Domain: cfg.auth0Domain,
+            clientId,
+            redirectUri: listener.redirectUri,
+            organization,
+            audience: cfg.audience,
+            state,
+            codeChallenge,
+        });
+        // The URL carries only public values (client id, PKCE challenge, state), so stderr is fine.
+        log(`Open this URL to sign in to ${domain}:\n${authorizeUrl}`, { quiet: false });
+        if (opts.browser !== false)
+            (deps.openBrowser ?? defaultOpenBrowser)(authorizeUrl);
+        let code;
+        try {
+            ;
+            ({ code } = await listener.result);
+        }
+        finally {
+            listener.close();
+        }
+        // 8. tokens
+        let tokens;
+        try {
+            tokens = await exchangeCode({ auth0Domain: cfg.auth0Domain, clientId, code, verifier, redirectUri: listener.redirectUri }, { fetch: doFetch });
+        }
+        catch (e) {
+            if (isUpstreamError(e))
+                throw createCliError('AUTH', `login failed: ${e.message}`);
+            throw e;
+        }
+        if (!tokens.refresh_token) {
+            throw createCliError('AUTH', 'login returned no refresh token (offline_access is not enabled for this app)');
+        }
+        // 9. consistency check (not a security boundary: every backend verifies the JWT)
+        const claims = decodeJwtPayload(tokens.access_token);
+        if (claims?.org_id !== organization || typeof claims.exp !== 'number' || typeof claims.sub !== 'string') {
+            throw createCliError('AUTH', 'login landed in a different organization');
+        }
+        const exp = claims.exp;
+        const sub = claims.sub;
+        // 10. proves the token works on Django
+        const me = await fetchMe(domain, { kind: 'bearer', token: tokens.access_token }, doFetch);
+        // 11. save (the lock is held only around the write, never while the browser is open)
+        const refreshToken = tokens.refresh_token;
+        await withDomainLock(domain, () => writeSession(domain, {
+            version: 1,
+            domain,
+            environment: cfg.environment,
+            auth0Domain: cfg.auth0Domain,
+            clientId,
+            audience: cfg.audience,
+            organization,
+            sub,
+            email: me.email,
+            accessToken: tokens.access_token,
+            accessTokenExpiresAt: exp,
+            refreshToken,
+            updatedAt: Math.floor(now() / 1000),
+        }, env), env);
+        log(`Logged in as ${me.email ?? sub} to ${domain}${cfg.environment === 'test' ? ' [test]' : ''}`, {
+            quiet: deps.quiet,
+        });
+        return ok({ domain, environment: cfg.environment, email: me.email, sub, expiresAt: exp });
+    }
+    catch (e) {
+        return fail(isCliError(e) ? e : createCliError('UNKNOWN', e instanceof Error ? e.message : String(e)));
+    }
+}
+export async function runLogout(opts, deps = {}) {
+    const env = deps.env ?? process.env;
+    try {
+        if (opts.all && opts.domain)
+            throw createCliError('VALIDATION', 'use a domain OR --all, not both');
+        const existing = listSessionDomains(env);
+        if (existing.length === 0) {
+            log('Not logged in', { quiet: deps.quiet });
+            return ok({ loggedOut: [] });
+        }
+        const domains = opts.all ? existing : [selectDomain({ domain: opts.domain }, env)];
+        for (const domain of domains) {
+            // ⛔ LOCAL ONLY, deliberately no Auth0 /oauth/revoke: the CLI shares ONE Native client id per tenant with
+            // the hosted MCP server, and with the tenant toggle "Refresh Token Revocation Deletes Grant" (not readable
+            // via the Management API, so it cannot be guaranteed off) a revoke kills EVERY refresh token for that
+            // user + client + audience, i.e. the user's ChatGPT/Claude connectors too. The token expires on its own.
+            await withDomainLock(domain, () => deleteSession(domain, env), env);
+            log(`Logged out of ${domain}`, { quiet: deps.quiet });
+        }
+        return ok({ loggedOut: domains });
+    }
+    catch (e) {
+        return fail(isCliError(e) ? e : createCliError('UNKNOWN', e instanceof Error ? e.message : String(e)));
+    }
+}
+/**
+ * One whoami row's status, matched on the specific failure (never "any AUTH"): only a session Auth0 or Django
+ * no longer accepts is `expired`; a held lock is `busy`; a file we refuse to read is `invalid session file`;
+ * anything else (network, 5xx) is `unreachable`.
+ */
+export function whoamiStatus(domain, e) {
+    const message = isCliError(e) ? e.message : '';
+    const expired = [' expired; ', 'refused the session', 'Not logged in to ', 'belongs to another organization'];
+    if (isCliError(e) && e.code === 'AUTH' && expired.some((m) => message.includes(m))) {
+        return `expired: run p login --domain ${domain}`;
+    }
+    if (message.includes('session is locked by another p process') ||
+        message.includes('session changed while refreshing')) {
+        return 'busy: another p process is using this session; retry';
+    }
+    if (/^session file /.test(message))
+        return `invalid session file: ${message}`;
+    return 'unreachable';
+}
+/** Never reads `--api-key`/`NG_API_KEY`; never returns a token. One bad session never fails the listing. */
+export async function runWhoami(opts, deps = {}) {
+    const env = deps.env ?? process.env;
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    try {
+        const explicit = opts.domain?.trim() || env.PITCHER_DOMAIN?.trim();
+        const domains = explicit ? [selectDomain(opts, env)] : listSessionDomains(env);
+        if (domains.length === 0)
+            throw createCliError('AUTH', 'Not logged in; run `p login`');
+        const sessions = [];
+        for (const domain of domains) {
+            const row = { domain, status: 'ok' };
+            try {
+                const s = readSession(domain, env);
+                row.environment = s?.environment;
+                row.email = s?.email;
+                const cred = await sessionCredential(domain, { ...deps.session, env });
+                row.expiresAt = readSession(domain, env)?.accessTokenExpiresAt;
+                const me = await fetchMe(domain, cred, doFetch);
+                row.email = me.email ?? row.email;
+            }
+            catch (e) {
+                row.status = whoamiStatus(domain, e);
+            }
+            sessions.push(row);
+        }
+        return ok({ sessions });
+    }
+    catch (e) {
+        return fail(isCliError(e) ? e : createCliError('UNKNOWN', e instanceof Error ? e.message : String(e)));
+    }
+}
+export function createLoginCommand() {
+    return new Command('login')
+        .description('Sign in to a Pitcher org in the browser; the session is stored per org domain')
+        .option('--domain <domain>', 'Your Pitcher web address, e.g. acme.my.pitcher.com')
+        .option('--no-browser', 'Print the sign-in URL instead of opening a browser')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runLogin(options, { quiet: globals.quiet }), globals);
+    });
+}
+export function createLogoutCommand() {
+    return new Command('logout')
+        .description('Sign out of one Pitcher org (or --all): deletes the local session only')
+        .argument('[domain]', 'The org domain to sign out of (needed when signed in to several)')
+        .option('--all', 'Sign out of every org')
+        .action(async (domain, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runLogout({ domain, all: options.all }, { quiet: globals.quiet }), globals);
+    });
+}
+export function createWhoamiCommand() {
+    return new Command('whoami')
+        .description('Show your p login sessions (or one, with --domain / PITCHER_DOMAIN)')
+        .option('--domain <domain>', 'Show only this org domain')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runWhoami(options), globals);
+    });
+}

package/dist/src/commands/mcp.js

@@ -3,10 +3,11 @@ import { runMcpServe } from '../mcp/serve.js';
 import { isCliError } from '../core/errors.js';
 export function createMcpCommand() {
     return new Command('mcp')
-        .description('Run the Pitcher MCP server over stdio (reads NG_API_KEY, NG_ORG/NG_URL, NG_ENV from env)')
-        .action(async () => {
+        .description('Run the LOCAL Pitcher MCP server over stdio: only dev_sync, dev_sync_revert, publish_app, on your `p login` session')
+        .option('--domain <domain>', 'p login session to serve, e.g. acme.my.pitcher.com (needed when signed in to several)')
+        .action(async (options) => {
         try {
-            await runMcpServe();
+            await runMcpServe({ domain: options.domain });
         }
         catch (e) {
             const message = isCliError(e) ? e.message : e instanceof Error ? e.message : String(e);

package/dist/src/commands/publishApp.d.ts

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import type { AxiosInstance } from 'axios';
-import { type Credential } from '../core/credential.js';
+import type { Credential } from '../core/credential.js';
 import { type Envelope } from '../core/envelope.js';
 interface PublishResult {
     app?: {
@@ -16,6 +16,7 @@ interface PublishOptions {
     folder?: string;
     apiKey?: string;
     credential?: Credential;
+    domain?: string;
     org?: string;
     url?: string;
     incrementVersion?: boolean;

package/dist/src/commands/publishApp.js

@@ -4,8 +4,7 @@ import os from 'os';
 import path from 'path';
 import { randomUUID } from 'crypto';
 import FormData from 'form-data';
-import { credentialOf } from '../core/credential.js';
-import { resolveBaseUrl } from '../core/baseUrl.js';
+import { resolveRequestTarget } from '../core/target.js';
 import { makeClient, toCliError } from '../core/http.js';
 import { zipDirectoryToFile } from '../core/archive.js';
 import { ok, fail } from '../core/envelope.js';
@@ -92,8 +91,10 @@ async function installToInstances(client, appName, instances, quiet) {
 }
 export async function runPublishApp(opts, deps = {}) {
     try {
-        const cred = credentialOf(opts);
-        const baseUrl = resolveBaseUrl({ org: opts.org, url: opts.url });
+        // On the key path (CI) `--publish-url` stays the exact POST target; on the session path its host must be
+        // the session's domain (resolveRequestTarget refuses anything else before a request is made).
+        const target = resolveRequestTarget(opts);
+        const baseUrl = target.baseUrl;
         const folderPath = path.resolve(opts.folder ?? '.');
         const appJsonPath = path.join(folderPath, 'app.json');
         const warnings = [];
@@ -124,7 +125,7 @@ export async function runPublishApp(opts, deps = {}) {
             fs.writeFileSync(appJsonPath, JSON.stringify(existingAppJson, null, 2));
             log(`Updated app.json version to ${nextVersion}`, { quiet: opts.quiet });
         }
-        const client = deps.client ?? makeClient(baseUrl, cred);
+        const client = deps.client ?? makeClient(baseUrl, target.source);
         const zipPath = path.join(deps.tmpDir ?? os.tmpdir(), `cli-publish-${process.pid}-${randomUUID()}.zip`);
         try {
             log(`Zipping ${folderPath}...`, { quiet: opts.quiet });
@@ -191,8 +192,9 @@ export async function runPublishApp(opts, deps = {}) {
 export function createPublishAppCommand() {
     return new Command('publish-app')
         .arguments('[folder]')
-        .option('--api-key <apiKey>', 'API Key for authentication')
-        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--api-key <apiKey>', 'API key (CI/automation only; people use `p login`)')
+        .option('--domain <domain>', 'p login session to use, e.g. acme.my.pitcher.com (see p whoami)')
+        .option('--org <organization>', 'Organization subdomain (with --api-key: default dev; with a session: picks it)')
         .option('--increment-version', 'Increment version in app.json')
         .option('--dry-run', 'Perform a dry run without publishing')
         .option('--publish-url <url>', 'Explicit publish URL')
@@ -204,6 +206,7 @@ export function createPublishAppCommand() {
         const env = await runPublishApp({
             folder,
             apiKey: options.apiKey,
+            domain: options.domain,
             org: options.org,
             url: options.publishUrl,
             incrementVersion: options.incrementVersion,

package/dist/src/commands/sharedLinks.d.ts

@@ -7,10 +7,8 @@ export interface SharedLinksDeps {
 }
 export declare function runSharedLinksCreate(opts: CommonOpts & {
     canvasId?: string;
-    fileId?: string;
 }, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
 export declare function runSharedLinksGet(opts: CommonOpts & {
     canvasId?: string;
-    fileId?: string;
 }, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
 export declare function createSharedLinksCommand(): Command;

package/dist/src/commands/sharedLinks.js

@@ -4,22 +4,17 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { withAuthFlags } from './withAuth.js';
-/** Enforce exactly one of --canvas-id / --file-id. Scope is derived from the target. */
-function requireOneTarget(opts) {
-    if (opts.canvasId && opts.fileId)
-        throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
-    if (opts.canvasId)
-        return 'canvas';
-    if (opts.fileId)
-        return 'file';
-    throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
+/** Only canvases can be shared. */
+function requireCanvasId(opts) {
+    if (!opts.canvasId)
+        throw createCliError('VALIDATION', '--canvas-id is required');
+    return opts.canvasId;
 }
 export async function runSharedLinksCreate(opts, deps = {}) {
     try {
-        const target = requireOneTarget(opts);
+        const canvasId = requireCanvasId(opts);
         const client = clientFor(opts, deps);
-        const body = target === 'canvas' ? { canvas_id: opts.canvasId } : { file_id: opts.fileId };
-        const res = await client.post('/api/v1/shared-links/', body);
+        const res = await client.post('/api/v1/shared-links/', { canvas_id: canvasId });
         return ok(res.data);
     }
     catch (e) {
@@ -28,13 +23,10 @@ export async function runSharedLinksCreate(opts, deps = {}) {
 }
 export async function runSharedLinksGet(opts, deps = {}) {
     try {
-        const target = requireOneTarget(opts);
+        const canvasId = requireCanvasId(opts);
         const client = clientFor(opts, deps);
         // encodeURIComponent so an id containing `/` or `..` can't retarget the request path
-        const path = target === 'canvas'
-            ? `/api/v1/shared-links/canvas/${encodeURIComponent(opts.canvasId)}`
-            : `/api/v1/shared-links/file/${encodeURIComponent(opts.fileId)}`;
-        const res = await client.get(path);
+        const res = await client.get(`/api/v1/shared-links/canvas/${encodeURIComponent(canvasId)}`);
         return ok(res.data);
     }
     catch (e) {
@@ -42,17 +34,15 @@ export async function runSharedLinksGet(opts, deps = {}) {
     }
 }
 export function createSharedLinksCommand() {
-    const cmd = new Command('shared-links').description('create and read share links for canvases and files');
+    const cmd = new Command('shared-links').description('create and read share links for canvases');
     withAuthFlags(cmd.command('create'))
         .option('--canvas-id <id>', 'Canvas to share')
-        .option('--file-id <id>', 'File to share')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runSharedLinksCreate({ ...options, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('get'))
         .option('--canvas-id <id>', 'Canvas whose link to fetch')
-        .option('--file-id <id>', 'File whose link to fetch')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runSharedLinksGet({ ...options, quiet: globals.quiet }), globals);

package/dist/src/commands/withAuth.d.ts

@@ -1,3 +1,7 @@
 import { Command } from 'commander';
-/** Attach the shared auth flags (--api-key/--org/--url) to a (sub)command. */
+/**
+ * Attach the shared auth flags to a (sub)command. People sign in with `p login` (`--domain` picks a session);
+ * `--api-key` is for automation. There is no commander default on `--org`: on the session path the session's
+ * org is the target, and only the key path falls back to `dev` (`resolveBaseUrl`).
+ */
 export declare function withAuthFlags(c: Command): Command;

package/dist/src/commands/withAuth.js

@@ -1,7 +1,12 @@
-/** Attach the shared auth flags (--api-key/--org/--url) to a (sub)command. */
+/**
+ * Attach the shared auth flags to a (sub)command. People sign in with `p login` (`--domain` picks a session);
+ * `--api-key` is for automation. There is no commander default on `--org`: on the session path the session's
+ * org is the target, and only the key path falls back to `dev` (`resolveBaseUrl`).
+ */
 export function withAuthFlags(c) {
     return c
-        .option('--api-key <apiKey>', 'API Key for authentication')
-        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--api-key <apiKey>', 'API key (CI/automation only; people use `p login`)')
+        .option('--domain <domain>', 'p login session to use, e.g. acme.my.pitcher.com (see p whoami)')
+        .option('--org <organization>', 'Organization subdomain (with --api-key: default dev; with a session: picks it)')
         .option('--url <url>', 'Explicit base URL override');
 }

package/dist/src/core/credential.d.ts

@@ -1,6 +1,8 @@
 /**
- * The credential a request is sent with. `apiKey` is the Knox key the CLI (and stdio `p mcp`) has
- * always used; `bearer` is a user's Auth0 access token, used by the hosted MCP server (PIT-8912).
+ * The credential a request is sent with. `apiKey` is a Knox key (automation, CI); `bearer` is a user's Auth0
+ * access token (`p login` sessions, the hosted MCP server). Resolution and the auth headers live in
+ * `target.ts` (`resolveRequestTarget`, `authHeaders`); this file is only the type, which `src/mcp/index.ts`
+ * re-exports for mcp-server.
  */
 export type Credential = {
     kind: 'bearer';
@@ -9,17 +11,3 @@ export type Credential = {
     kind: 'apiKey';
     key: string;
 };
-/** The auth header(s) for a credential. Exactly one header, never both. */
-export declare function authHeaders(c: Credential): Record<string, string>;
-/**
- * The ONE credential resolver every call site uses.
- *
- * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
- * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
- * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
- * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
- */
-export declare function credentialOf(opts: {
-    apiKey?: string;
-    credential?: Credential;
-}): Credential;

package/dist/src/core/credential.js

@@ -1,25 +1 @@
-import { resolveApiKey } from './auth.js';
-import { createCliError } from './errors.js';
-/** The auth header(s) for a credential. Exactly one header, never both. */
-export function authHeaders(c) {
-    return c.kind === 'bearer' ? { authorization: `Bearer ${c.token}` } : { 'x-api-key': c.key };
-}
-/**
- * The ONE credential resolver every call site uses.
- *
- * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
- * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
- * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
- * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
- */
-export function credentialOf(opts) {
-    const c = opts.credential;
-    if (c) {
-        const value = c.kind === 'bearer' ? c.token : c.key;
-        if (typeof value !== 'string' || !value.trim()) {
-            throw createCliError('AUTH', `Empty ${c.kind === 'bearer' ? 'bearer token' : 'API key'} credential`);
-        }
-        return c;
-    }
-    return { kind: 'apiKey', key: resolveApiKey(opts) };
-}
+export {};

package/dist/src/core/http.d.ts

@@ -1,13 +1,22 @@
 import { type AxiosInstance } from 'axios';
-import { type Credential } from './credential.js';
+import type { Credential } from './credential.js';
 import { type CliError } from './errors.js';
-export declare function makeClient(baseUrl: string, cred: Credential, opts?: {
+import { type CredentialSource } from './target.js';
+/**
+ * A static credential sets its header once, exactly as before. A function source (a `p login` session) is
+ * awaited PER REQUEST by an interceptor, so a long-running client (`dev-sync watch`) picks up a refreshed
+ * token and every builder stays synchronous.
+ */
+export declare function makeClient(baseUrl: string, source: CredentialSource, opts?: {
     maxRedirects?: number;
+    headers?: Record<string, string>;
 }): AxiosInstance;
 export interface CommonOpts {
     apiKey?: string;
-    /** Explicit credential (hosted MCP: a user's bearer token). Wins over `apiKey`/`NG_API_KEY` — see `credentialOf`. */
+    /** Explicit credential (hosted MCP: a user's bearer token). Wins over everything — see `resolveRequestTarget`. */
     credential?: Credential;
+    /** A `p login` session domain (`acme.my.pitcher.com`); cannot be combined with `--org` or `--api-key`. */
+    domain?: string;
     org?: string;
     url?: string;
     quiet?: boolean;
@@ -18,10 +27,9 @@ export declare function clientFor(opts: CommonOpts, deps?: {
 }): AxiosInstance;
 export declare const CLICKHOUSE_API_BASE_URL = "https://clickhouse.pitcher.com";
 /**
- * Client for the clickhouse-api analytics service (PIT-7647). The service lives
- * on ONE host for every env/region; `x-original-domain` (the same `--org`/`--url`
- * resolution as Django calls) is what routes the request to the right core for
- * key validation + tenant scoping, so the usual flags select test vs prod.
+ * Client for the clickhouse-api analytics service (PIT-7647). The service lives on ONE host for every
+ * env/region; `x-original-domain` routes the request to the right core for key/token validation and tenant
+ * scoping. It is the TARGET's host, so a session call is scoped to the session's org, never a default.
  */
 export declare function clickhouseClientFor(opts: CommonOpts, deps?: {
     client?: AxiosInstance;