@pitcher/cli-scripts 2.21.0 → 3.0.1

package/dist/src/core/session.js

@@ -0,0 +1,293 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createCliError } from './errors.js';
+import { isUpstreamError, normalizeDomain, refresh as auth0Refresh } from './pitcherAuth.js';
+const SESSION_FILE = /^[a-z0-9-]+\.my\.pitcher\.com\.json$/;
+/** Refresh this many seconds before the access token expires. */
+const EXPIRY_SKEW_SEC = 120;
+const LOCK_RETRY_MS = 100;
+const LOCK_TIMEOUT_MS = 10000;
+const LOCK_STALE_MS = 30000;
+const loginHint = (domain) => `run \`p login --domain ${domain}\``;
+export function configRoot(env = process.env) {
+    if (env.PITCHER_CONFIG_DIR)
+        return env.PITCHER_CONFIG_DIR;
+    return path.join(env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'pitcher');
+}
+export function sessionsDir(env = process.env) {
+    return path.join(configRoot(env), 'sessions');
+}
+/** Only call with a normalized domain (the allowlist makes it a safe file name). */
+export function sessionPath(domain, env = process.env) {
+    return path.join(sessionsDir(env), `${domain}.json`);
+}
+/** Sorted. Inclusion match on the file name, so stray files (temp, lock, .DS_Store) are never sessions. */
+export function listSessionDomains(env = process.env) {
+    const dir = sessionsDir(env);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => SESSION_FILE.test(f))
+        .map((f) => f.slice(0, -'.json'.length))
+        .sort();
+}
+/** null = no file. AUTH on too-open permissions, bad JSON, an unknown version, or a domain ≠ the file name. */
+export function readSession(domain, env = process.env) {
+    const file = sessionPath(domain, env);
+    let raw;
+    try {
+        if (process.platform !== 'win32' && (statSync(file).mode & 0o077) !== 0) {
+            throw createCliError('AUTH', `session file permissions are too open; run \`chmod 600 ${file}\` or \`p login --domain ${domain}\``);
+        }
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+    let s;
+    try {
+        s = JSON.parse(raw);
+    }
+    catch {
+        throw createCliError('AUTH', `session file ${file} is not valid JSON; ${loginHint(domain)}`);
+    }
+    if (s?.version !== 1)
+        throw createCliError('AUTH', `session file ${file} has an unknown version; ${loginHint(domain)}`);
+    if (s.domain !== domain) {
+        throw createCliError('AUTH', `session file ${file} belongs to another domain; ${loginHint(domain)}`);
+    }
+    return s;
+}
+function ensureDirs(env) {
+    const root = configRoot(env);
+    const dir = sessionsDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Either directory may predate us with a looser mode.
+    chmodSync(root, 0o700);
+    chmodSync(dir, 0o700);
+}
+/** Atomic replace of ONE domain's session; other domains are untouched. The caller holds the domain lock. */
+export function writeSession(domain, s, env = process.env) {
+    ensureDirs(env);
+    const file = sessionPath(domain, env);
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+        writeSync(fd, JSON.stringify(s, null, 2) + '\n');
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, file);
+}
+/** The caller holds the domain lock. */
+export function deleteSession(domain, env = process.env) {
+    try {
+        unlinkSync(sessionPath(domain, env));
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+}
+/**
+ * The ONE domain picker every session consumer uses: `--domain` (or `logout`'s positional) → `PITCHER_DOMAIN`
+ * → the single existing session. Never "most recent wins": a silent pick could send a prod write to the
+ * wrong org, so two or more sessions with nothing explicit is a VALIDATION error.
+ */
+export function selectDomain(opts, env = process.env) {
+    const explicit = opts.domain?.trim() || env.PITCHER_DOMAIN?.trim();
+    if (explicit) {
+        const n = normalizeDomain(explicit);
+        if (!n.ok)
+            throw createCliError('VALIDATION', n.error);
+        if (!existsSync(sessionPath(n.domain, env))) {
+            throw createCliError('AUTH', `Not logged in to ${n.domain}; ${loginHint(n.domain)}`);
+        }
+        return n.domain;
+    }
+    const all = listSessionDomains(env);
+    if (all.length === 0)
+        throw createCliError('AUTH', 'Not logged in; run `p login`');
+    if (all.length === 1)
+        return all[0];
+    throw createCliError('VALIDATION', `Logged in to several Pitcher orgs (${all.join(', ')}); pass --domain or set PITCHER_DOMAIN`);
+}
+// ── per-domain lock ────────────────────────────────────────────────────────────────────────────────────────
+const lockPath = (domain, env) => `${sessionPath(domain, env)}.lock`;
+function readOrNull(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Break a lock that was observed stale with content `observed`, without the unlink race: MOVE it aside
+ * (only one waiter can move a given inode), then compare what was moved. Our stale lock → drop it. Someone
+ * else's fresh lock (created after we looked) → put it back with `link`, which fails harmlessly if an even
+ * newer lock exists. Exported for the tests.
+ */
+export function breakStaleLock(lock, observed, waiterToken) {
+    const moved = `${lock}.${waiterToken}.stale`;
+    try {
+        renameSync(lock, moved);
+    }
+    catch {
+        return; // already gone or moved by another waiter
+    }
+    const content = readOrNull(moved);
+    if (content !== observed) {
+        try {
+            linkSync(moved, lock);
+        }
+        catch {
+            // a newer lock already exists: leave it
+        }
+    }
+    try {
+        unlinkSync(moved);
+    }
+    catch {
+        // nothing to clean up
+    }
+}
+/** Serialise `fn` per domain across processes (`<domain>.json.lock`, `wx`). AUTH after 10 s of waiting. */
+export async function withDomainLock(domain, fn, env = process.env, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const lock = lockPath(domain, env);
+    const token = randomBytes(16).toString('hex');
+    const started = now();
+    ensureDirs(env);
+    for (;;) {
+        try {
+            const fd = openSync(lock, 'wx', 0o600);
+            try {
+                writeSync(fd, JSON.stringify({ token, ts: now() }));
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        const observed = readOrNull(lock);
+        if (observed !== null) {
+            let ts;
+            try {
+                ts = JSON.parse(observed).ts;
+            }
+            catch {
+                ts = undefined; // being written right now: not stale
+            }
+            if (typeof ts === 'number' && now() - ts > (opts.staleMs ?? LOCK_STALE_MS)) {
+                breakStaleLock(lock, observed, token);
+                continue;
+            }
+        }
+        if (now() - started > (opts.timeoutMs ?? LOCK_TIMEOUT_MS)) {
+            throw createCliError('AUTH', 'session is locked by another p process');
+        }
+        await new Promise((r) => setTimeout(r, opts.retryMs ?? LOCK_RETRY_MS));
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // Release only a lock that is still ours (a waiter may have broken it as stale).
+        const content = readOrNull(lock);
+        try {
+            if (content !== null && JSON.parse(content).token === token)
+                unlinkSync(lock);
+        }
+        catch {
+            // unreadable or already gone
+        }
+    }
+}
+// ── credential + refresh ───────────────────────────────────────────────────────────────────────────────────
+/** Decode (NOT verify) a JWT payload. The CLI is not a security boundary here: every backend verifies. */
+export function decodeJwtPayload(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return null;
+        const json = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+        return json && typeof json === 'object' ? json : null;
+    }
+    catch {
+        return null;
+    }
+}
+const isFresh = (s, nowMs) => s.accessTokenExpiresAt - EXPIRY_SKEW_SEC > nowMs / 1000;
+/**
+ * The session's bearer, refreshed when it is within 120 s of expiry. A refresh runs under the domain lock:
+ * re-read (another process may have refreshed), refresh, re-check `org_id`, then compare-and-write the
+ * rotated RT BEFORE returning the access token.
+ */
+export async function sessionCredential(domain, opts = {}) {
+    const env = opts.env ?? process.env;
+    const now = opts.now ?? Date.now;
+    const refresh = opts.auth0?.refresh ?? ((p) => auth0Refresh(p));
+    const first = readSession(domain, env);
+    if (!first)
+        throw createCliError('AUTH', `Not logged in to ${domain}; ${loginHint(domain)}`);
+    if (isFresh(first, now()))
+        return { kind: 'bearer', token: first.accessToken };
+    return withDomainLock(domain, async () => {
+        const s = readSession(domain, env);
+        if (!s)
+            throw createCliError('AUTH', `Not logged in to ${domain}; ${loginHint(domain)}`);
+        if (isFresh(s, now()))
+            return { kind: 'bearer', token: s.accessToken };
+        const sentRt = s.refreshToken;
+        let t;
+        try {
+            t = await refresh({ auth0Domain: s.auth0Domain, clientId: s.clientId, refreshToken: sentRt });
+        }
+        catch (e) {
+            if (isUpstreamError(e) && e.kind === 'grant') {
+                // Compare-and-delete: never delete a session we did not read.
+                if (readSession(domain, env)?.refreshToken === sentRt)
+                    deleteSession(domain, env);
+                throw createCliError('AUTH', `Your session for ${domain} expired; ${loginHint(domain)}`);
+            }
+            throw createCliError('AUTH', `could not refresh the ${domain} session (network)`);
+        }
+        const claims = decodeJwtPayload(t.access_token);
+        // Auth0 has already rotated sentRt, so it is spent: replaying it later trips reuse detection, which
+        // revokes the token family and the user's SSO session. Compare-and-delete instead of leaving it on disk.
+        const rejectRotated = (why) => {
+            if (readSession(domain, env)?.refreshToken === sentRt)
+                deleteSession(domain, env);
+            return createCliError('AUTH', `${why}; ${loginHint(domain)}`);
+        };
+        if (claims?.org_id !== s.organization)
+            throw rejectRotated('refreshed token belongs to another organization');
+        if (typeof claims.exp !== 'number')
+            throw rejectRotated('refreshed token has no expiry');
+        // Compare-and-write: only if the file still holds the RT we sent.
+        const current = readSession(domain, env);
+        if (current?.refreshToken !== sentRt) {
+            if (current && isFresh(current, now()))
+                return { kind: 'bearer', token: current.accessToken };
+            throw createCliError('AUTH', `session changed while refreshing; retry`);
+        }
+        writeSession(domain, {
+            ...current,
+            accessToken: t.access_token,
+            accessTokenExpiresAt: claims.exp,
+            refreshToken: t.refresh_token ?? sentRt,
+            updatedAt: Math.floor(now() / 1000),
+        }, env);
+        return { kind: 'bearer', token: t.access_token };
+    }, env, opts.lock);
+}

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

@@ -0,0 +1,47 @@
+import type { Credential } from './credential.js';
+/**
+ * The ONE target resolver: credential AND origin come from the same rule, so a `p login` token can never be
+ * sent to a host another rule picked (PIT-8943, D-14). Every client builder goes through here.
+ *
+ * ⛔ Bypass guard (`test/commands/noBypass.test.ts`): outside this file and `baseUrl.ts`, nothing under `src/`
+ * may call `resolveBaseUrl(` / `resolveApiKey(` or write an auth header literal. That is why `authHeaders` and
+ * `resolveApiKey` live HERE.
+ */
+/** A static credential, or one resolved per request (a session refreshes when its access token nears expiry). */
+export type CredentialSource = Credential | (() => Promise<Credential>);
+export interface RequestTarget {
+    /** Origin, e.g. `https://acme.my.pitcher.com` */
+    baseUrl: string;
+    /** `new URL(baseUrl).hostname`: NO port */
+    host: string;
+    source: CredentialSource;
+    via: 'explicit' | 'apiKeyFlag' | 'session' | 'apiKeyEnv';
+}
+export interface TargetOpts {
+    apiKey?: string;
+    /** Explicit credential (the hosted MCP server's bearer, or local `p mcp`'s resolved session). */
+    credential?: Credential;
+    /** A `p login` session domain (`acme.my.pitcher.com`). */
+    domain?: string;
+    org?: string;
+    url?: string;
+}
+export interface TargetDeps {
+    /** Where the precedence notices go. Default: stderr, each notice once per process. */
+    warn?: (message: string) => void;
+    isTty?: boolean;
+}
+/** The auth header(s) for a credential. Exactly one header, never both. */
+export declare function authHeaders(c: Credential): Record<string, string>;
+/** `--api-key` then `NG_API_KEY` (trimmed; blank = absent). Only the target resolver calls it. */
+export declare function resolveApiKey(opts: {
+    apiKey?: string;
+}, env?: NodeJS.ProcessEnv): string;
+/**
+ * Precedence: explicit credential → `--api-key` → a `p login` session → `NG_API_KEY` (OD-4: an exported key
+ * never shadows a login) → AUTH. With sessions present but the domain ambiguous or not logged in, the result is
+ * `selectDomain`'s error, NEVER a silent fall back to `NG_API_KEY`.
+ */
+export declare function resolveRequestTarget(opts: TargetOpts, env?: NodeJS.ProcessEnv, deps?: TargetDeps): RequestTarget;
+/** Resolve a source to a concrete credential (static as is, or a session's possibly refreshed bearer). */
+export declare function credentialFrom(source: CredentialSource): Promise<Credential>;

package/dist/src/core/target.js

@@ -0,0 +1,114 @@
+import { resolveBaseUrl } from './baseUrl.js';
+import { createCliError } from './errors.js';
+import { normalizeDomain } from './pitcherAuth.js';
+import { listSessionDomains, selectDomain, sessionCredential } from './session.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 };
+}
+/** `--api-key` then `NG_API_KEY` (trimmed; blank = absent). Only the target resolver calls it. */
+export function resolveApiKey(opts, env = process.env) {
+    const flagKey = opts.apiKey?.trim();
+    if (flagKey)
+        return flagKey;
+    const envKey = env.NG_API_KEY?.trim();
+    if (envKey)
+        return envKey;
+    throw createCliError('AUTH', 'API key is required. Provide --api-key or set the NG_API_KEY environment variable.');
+}
+const NOT_LOGGED_IN = 'Not logged in. Run `p login` (automation: pass --api-key).';
+const KEY_ON_TTY = 'API keys are for automation; run `p login` for your own account';
+const ENV_KEY_IGNORED = 'NG_API_KEY ignored: using your p login session (pass --api-key to use a key)';
+const warnedOnce = new Set();
+function defaultWarn(message) {
+    if (warnedOnce.has(message))
+        return;
+    warnedOnce.add(message);
+    process.stderr.write(`warning: ${message}\n`);
+}
+function checkedExplicit(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;
+}
+const hostOf = (baseUrl) => new URL(baseUrl).hostname;
+/**
+ * The session domain an explicit `--url`/`--publish-url` names, or a refusal. Only `https://<org>.my.pitcher.com`
+ * (no port) can carry a session token; anything else would hand the user's token to another host.
+ */
+function sessionDomainOfUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw createCliError('VALIDATION', `Invalid base URL: ${url}`);
+    }
+    const n = normalizeDomain(u.hostname);
+    if (u.protocol !== 'https:' || u.port || !n.ok || n.domain !== u.hostname) {
+        throw createCliError('VALIDATION', `refusing to send your Pitcher session to ${u.host}`);
+    }
+    return n.domain;
+}
+/**
+ * Precedence: explicit credential → `--api-key` → a `p login` session → `NG_API_KEY` (OD-4: an exported key
+ * never shadows a login) → AUTH. With sessions present but the domain ambiguous or not logged in, the result is
+ * `selectDomain`'s error, NEVER a silent fall back to `NG_API_KEY`.
+ */
+export function resolveRequestTarget(opts, env = process.env, deps = {}) {
+    const warn = deps.warn ?? defaultWarn;
+    const isTty = deps.isTty ?? Boolean(process.stderr.isTTY);
+    const warnKeyOnTty = () => {
+        if (isTty && !env.CI)
+            warn(KEY_ON_TTY);
+    };
+    // 0.
+    if (opts.domain && opts.org)
+        throw createCliError('VALIDATION', 'use --domain OR --org, not both');
+    // 1. explicit credential (hosted MCP, local p mcp): never falls through, fails closed.
+    if (opts.credential) {
+        const baseUrl = resolveBaseUrl({ org: opts.org, url: opts.url });
+        return { baseUrl, host: hostOf(baseUrl), source: checkedExplicit(opts.credential), via: 'explicit' };
+    }
+    // 2. --api-key flag (automation)
+    const flagKey = opts.apiKey?.trim();
+    if (flagKey) {
+        if (opts.domain) {
+            throw createCliError('VALIDATION', '--domain selects a p login session; with --api-key use --org/--url');
+        }
+        warnKeyOnTty();
+        const baseUrl = resolveBaseUrl({ org: opts.org, url: opts.url });
+        return { baseUrl, host: hostOf(baseUrl), source: { kind: 'apiKey', key: flagKey }, via: 'apiKeyFlag' };
+    }
+    // 3. a p login session
+    if (listSessionDomains(env).length > 0) {
+        const urlDomain = opts.url ? sessionDomainOfUrl(opts.url) : undefined;
+        const named = opts.domain ?? (opts.org ? `${opts.org}.my.pitcher.com` : undefined);
+        const domain = selectDomain({ domain: named ?? urlDomain }, env);
+        if (urlDomain && urlDomain !== domain) {
+            throw createCliError('VALIDATION', `refusing to send your Pitcher session to ${urlDomain}`);
+        }
+        if (env.NG_API_KEY?.trim())
+            warn(ENV_KEY_IGNORED);
+        const baseUrl = `https://${domain}`;
+        return { baseUrl, host: domain, source: () => sessionCredential(domain, { env }), via: 'session' };
+    }
+    // --domain names a session, and none exist.
+    if (opts.domain)
+        selectDomain({ domain: opts.domain }, env);
+    // 4. NG_API_KEY (CI: no session exists, so CI is unaffected)
+    const envKey = env.NG_API_KEY?.trim();
+    if (envKey) {
+        warnKeyOnTty();
+        const baseUrl = resolveBaseUrl({ org: opts.org, url: opts.url });
+        return { baseUrl, host: hostOf(baseUrl), source: { kind: 'apiKey', key: envKey }, via: 'apiKeyEnv' };
+    }
+    // 5.
+    throw createCliError('AUTH', NOT_LOGGED_IN);
+}
+/** Resolve a source to a concrete credential (static as is, or a session's possibly refreshed bearer). */
+export async function credentialFrom(source) {
+    return typeof source === 'function' ? source() : source;
+}

package/dist/src/mcp/local.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The tool set of LOCAL `p mcp` (PIT-8943): only the three disk-bound tools (`dev_sync`, `dev_sync_revert`,
+ * `publish_app`), which zip a folder on this machine and so cannot run hosted. Everything else is the hosted
+ * server (`https://pitcher-mcp.fly.dev/mcp`).
+ */
+export declare const localTools: import("./index.js").ToolDescriptor[];

package/dist/src/mcp/local.js

@@ -0,0 +1,8 @@
+import { LOCAL_ONLY } from './hosted.js';
+import { allTools } from './registry.js';
+/**
+ * The tool set of LOCAL `p mcp` (PIT-8943): only the three disk-bound tools (`dev_sync`, `dev_sync_revert`,
+ * `publish_app`), which zip a folder on this machine and so cannot run hosted. Everything else is the hosted
+ * server (`https://pitcher-mcp.fly.dev/mcp`).
+ */
+export const localTools = allTools.filter((t) => LOCAL_ONLY.has(t.name));

package/dist/src/mcp/serve.d.ts

@@ -1,4 +1,19 @@
-import type { ToolDescriptor } from './tools/types.js';
-import type { PromptDescriptor } from './prompts/types.js';
-import type { ResourceDescriptor } from './resources/types.js';
-export declare function runMcpServe(env?: NodeJS.ProcessEnv, tools?: ToolDescriptor[], prompts?: PromptDescriptor[], resources?: ResourceDescriptor[]): Promise<void>;
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SessionCredentialOpts } from '../core/session.js';
+export interface LocalServer {
+    server: McpServer;
+    domain: string;
+    destructiveWrites: boolean;
+}
+/**
+ * The local `p mcp` server on the `p login` session (PIT-8943). The domain is picked once with `selectDomain`
+ * (`--domain` → `PITCHER_DOMAIN` → the only session) and fixed for the life of the process; API keys are never
+ * read. `session` is a test seam for the refresh clock and Auth0.
+ */
+export declare function buildLocalServer(opts?: {
+    domain?: string;
+}, env?: NodeJS.ProcessEnv, session?: Omit<SessionCredentialOpts, 'env'>): Promise<LocalServer>;
+/** `p mcp`: connect the local server over stdio. Never writes to stdout except protocol frames. */
+export declare function runMcpServe(opts?: {
+    domain?: string;
+}, env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/src/mcp/serve.js

@@ -1,18 +1,41 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { resolveMcpEnv } from './env.js';
+import { createCliError } from '../core/errors.js';
+import { orgSubdomain } from '../core/pitcherAuth.js';
+import { readSession, selectDomain, sessionCredential } from '../core/session.js';
+import { localTools } from './local.js';
 import { buildServer } from './server.js';
-import { allTools } from './registry.js';
-import { allPrompts } from './prompts/registry.js';
-import { allResources } from './resources/registry.js';
-// Resolves auth/env, builds the server, connects stdio. Never writes to stdout except protocol frames.
-// `tools` defaults to the full set (the CLI `p mcp`); the .mcpb bundle passes a curated subset.
-// Prompts/resources default to the full set for every frontend (no subsetting).
-export async function runMcpServe(env = process.env, tools = allTools, prompts = allPrompts, resources = allResources) {
-    const mcpEnv = resolveMcpEnv(env);
-    const server = buildServer({ credential: { kind: 'apiKey', key: mcpEnv.apiKey }, org: mcpEnv.org, url: mcpEnv.url }, tools, prompts, resources, { destructiveWrites: mcpEnv.prod });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    const target = mcpEnv.url ?? `https://${mcpEnv.org}.my.pitcher.com`;
-    console.error(`[pitcher-mcp] serving ${tools.length} tools, ${prompts.length} prompts, ${resources.length} resources ` +
-        `against ${target}${mcpEnv.prod ? ' (prod: destructive-hints on)' : ''}`);
+/**
+ * The local `p mcp` server on the `p login` session (PIT-8943). The domain is picked once with `selectDomain`
+ * (`--domain` → `PITCHER_DOMAIN` → the only session) and fixed for the life of the process; API keys are never
+ * read. `session` is a test seam for the refresh clock and Auth0.
+ */
+export async function buildLocalServer(opts = {}, env = process.env, session = {}) {
+    const domain = selectDomain(opts, env);
+    const s = readSession(domain, env);
+    if (!s)
+        throw createCliError('AUTH', `Not logged in to ${domain}; run \`p login --domain ${domain}\``);
+    // FAIL CLOSED: `environment` is optional upstream, so unknown is treated as production.
+    const destructiveWrites = s.environment !== 'test';
+    const credentialOpts = { ...session, env };
+    const server = buildServer({
+        // Boot check: a dead session fails at start, not on the first tool call.
+        credential: await sessionCredential(domain, credentialOpts),
+        resolveCredential: async () => {
+            if (!readSession(domain, env)) {
+                throw createCliError('AUTH', `Logged out of ${domain}; run \`p login --domain ${domain}\` and restart`);
+            }
+            return sessionCredential(domain, credentialOpts);
+        },
+        // NEVER `url`: runPublishApp treats `url` as the publish endpoint, so the org is what targets the session.
+        org: orgSubdomain(domain),
+    }, localTools, [], // no prompts/resources: none references a local tool
+    [], { destructiveWrites });
+    return { server, domain, destructiveWrites };
+}
+/** `p mcp`: connect the local server over stdio. Never writes to stdout except protocol frames. */
+export async function runMcpServe(opts = {}, env = process.env) {
+    const { server, domain, destructiveWrites } = await buildLocalServer(opts, env);
+    await server.connect(new StdioServerTransport());
+    console.error(`[pitcher-mcp] serving ${localTools.length} local tools against https://${domain}` +
+        (destructiveWrites ? ' (destructive-hints on)' : ''));
 }

package/dist/src/mcp/server.d.ts

@@ -5,11 +5,13 @@ import type { PromptDescriptor } from './prompts/types.js';
 import type { ResourceDescriptor } from './resources/types.js';
 /**
  * The per-server request context: who every tool call runs as, and against which origin.
- * A plain value captured at build time — stdio builds one from env (API key); the hosted server
+ * Captured at build time — local stdio `p mcp` builds one from the `p login` session; the hosted server
  * builds one server per request from the caller's bearer token. Never a tool input.
  */
 export interface McpRunContext {
     credential: Credential;
+    /** Local stdio only: resolved before EVERY tool call (refresh-aware). When set it wins over `credential`. Hosted never sets it. */
+    resolveCredential?: () => Promise<Credential>;
     org?: string;
     url?: string;
 }

package/dist/src/mcp/server.js

@@ -9,11 +9,6 @@ import { envelopeToToolResult, toErrorResult } from './result.js';
 import { ANALYTICS_RENDER_POLICY } from './renderPolicy.js';
 import { isCliError } from '../core/errors.js';
 const version = (() => {
-    // The .mcpb bundle inlines this at build time (esbuild define) because the bundled single
-    // file has no package.json to walk to. Undefined at CLI runtime → the readFileSync path below.
-    const injected = process.env.PITCHER_CLI_VERSION;
-    if (injected)
-        return injected;
     try {
         const dir = dirname(fileURLToPath(import.meta.url));
         return JSON.parse(readFileSync(join(dir, '..', '..', '..', 'package.json'), 'utf8')).version ?? '0.0.0';
@@ -55,8 +50,9 @@ export function buildServer(ctx, tools = allTools, prompts = allPrompts, resourc
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: destructive },
         }, async (args) => {
             try {
+                const credential = ctx.resolveCredential ? await ctx.resolveCredential() : ctx.credential;
                 // spread args FIRST so injected auth/env always wins — never reorder to { credential, ...args }
-                const envelope = await tool.run({ ...args, credential: ctx.credential, org: ctx.org, url: ctx.url });
+                const envelope = await tool.run({ ...args, credential, org: ctx.org, url: ctx.url });
                 return envelopeToToolResult(envelope);
             }
             catch (e) {

package/dist/src/mcp/tools/analytics.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { KPI_TYPES } from '../../core/kpiTypes.js';
 import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, } from '../../commands/analytics.js';
 export const analyticsTools = [
     {
@@ -21,11 +22,11 @@ export const analyticsTools = [
         name: 'pitcher_analytics_kpi',
         title: 'Instance KPI metrics',
         description: 'Read KPI metrics for an instance from the clickhouse analytics service (PIT-7647). ' +
-            'Access follows the API key user’s real role; activity-metric types need start/end dates ' +
+            'Access follows the signed-in user’s own role; activity-metric types need start/end dates ' +
             '(inventory counts like total-members do not).',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
-            type: z.string().describe('KPI type, e.g. total-members, total-active-users (required)'),
+            type: z.enum(KPI_TYPES).describe('KPI type'),
             startDate: z.string().optional().describe('Window start, ISO date (required by the server for activity metrics)'),
             endDate: z.string().optional().describe('Window end, ISO date (required by the server for activity metrics)'),
             groupIds: z.string().optional().describe('Comma-separated distribution-group IDs to scope by'),

package/dist/src/mcp/tools/publishApp.js

@@ -12,7 +12,7 @@ export const publishAppTools = [
             'optionally installing it to specific instances or all instances of an environment afterward. ' +
             'Consequential: this creates a live, org-visible app release — use dryRun to preview first. ' +
             'Re-publishing an already-existing version is a no-op (returns ok with a warning), not a failure. ' +
-            'Publish targets the org resolved from NG_ORG; the injected NG_URL is not used as the publish endpoint.',
+            'Publishes to the org of the `p login` session this server runs on.',
         inputShape: {
             folder: z.string().optional().describe('Local folder to zip and publish (defaults to the MCP server cwd)'),
             incrementVersion: z.boolean().optional().describe('Bump the version in app.json before publishing'),
@@ -20,8 +20,8 @@ export const publishAppTools = [
             installTo: z.string().optional().describe('Comma-separated instance IDs to install the app to after publishing'),
             installToEnvName: z.string().optional().describe('Environment name (e.g. "test") to install the app to after publishing'),
         },
-        // runPublishApp overloads `url` as BOTH origin and publish endpoint; the server injects NG_URL into
-        // every tool, so forward only apiKey + credential + org (never url) plus this tool's own inputs.
+        // runPublishApp overloads `url` as BOTH origin and publish endpoint, so forward only apiKey + credential +
+        // org (never url) plus this tool's own inputs; local `p mcp` targets its session through `org`.
         run: (opts) => runPublishApp({
             folder: asString(opts.folder),
             incrementVersion: asBool(opts.incrementVersion),