@credibledata/cred-cli 0.0.105 → 0.0.106

package/dist/setup-core/credstore.d.ts

@@ -0,0 +1,229 @@
+import { type ResolvedTokens } from "@credibledata/cli-auth";
+export type { ResolvedTokens };
+import { Environment } from "./environments";
+/**
+ * The `~/.cred` credential store, shared by the `cred` CLI and the VS Code
+ * extension.
+ *
+ * ## Why token reads are claim-based, not field-based
+ *
+ * The two tools disagree about what the `accessToken` FIELD holds:
+ *
+ *   - the CLI writes the Auth0 **access token** there (`login.ts`), and sends it
+ *     as `Bearer` to the control plane;
+ *   - the extension writes the **id token** there on every refresh
+ *     (`vscode-ext/src/user/user.ts`), and keeps the access token in
+ *     `jwtAccessToken`.
+ *
+ * Whichever tool wrote last decides what the field means, so reading it by name
+ * makes the CLI's behaviour depend on a race. Instead every read resolves the
+ * token it wants by inspecting the JWT's `aud` claim: the access token is
+ * audienced to the Auth0 API, the id token to the client id. Both are known per
+ * deployment env, so classification is exact rather than heuristic.
+ *
+ * This is a PERMANENT contract, not a migration step. The shipped extension
+ * keeps writing the old shape on every refresh, so a one-time fixup would be
+ * undone within minutes of the user opening VS Code. It can be deleted only
+ * once the extension writes the same shape (Phase 2 of the local-devex plan).
+ *
+ * A schema-version marker was considered and rejected for the same reason: the
+ * extension mutates the file after we stamp it, so a version field would claim
+ * a shape the file no longer has. Claim-based classification needs no marker
+ * because it reads the tokens themselves.
+ *
+ * Writes stay in the shape the extension already understands — `accessToken`
+ * and `jwtAccessToken` both set to the access token, `idToken` added alongside —
+ * so nothing about this change alters what the extension sees today.
+ */
+interface StoredEnvConfig {
+    organization?: string;
+    project?: string;
+    auth?: {
+        username: string;
+        password: string;
+    };
+    vsCodeUser?: {
+        username: string;
+        email: string;
+    };
+    /**
+     * Ambiguous by history: the access token when the CLI wrote it, the id token
+     * when the extension did. Never read by name — see {@link resolveTokens}.
+     */
+    accessToken?: string;
+    /** The access token, per the extension's convention. Also written by the CLI. */
+    jwtAccessToken?: string;
+    /** The id token. Written by this CLI only; absent in files the extension wrote. */
+    idToken?: string;
+    refreshToken?: string;
+    isServiceAccountToken?: boolean;
+}
+interface ConfigFile {
+    configPerEnvironment: Partial<Record<Environment, StoredEnvConfig>>;
+    activeEnvironment: Environment;
+}
+/**
+ * Thrown when `.cred` exists but cannot be used: either it does not parse as
+ * JSON or it parses but lacks the required top-level shape. Distinct from fs
+ * errors (ENOENT, EACCES) so callers that want to recover — `cred login` —
+ * can target *only* a corrupt-content failure and leave permission/IO errors
+ * to surface loudly.
+ */
+export declare class InvalidConfigError extends Error {
+}
+/**
+ * Sort the stored token fields into access token and id token by audience,
+ * using the rules `cred` and `ms2ad` share (cli-auth/src/index.ts, where each
+ * rule is written down and tested), bound to this deployment's Auth0 values.
+ *
+ * A token it cannot identify comes back `undefined`, so the caller says "run
+ * `cred login`" instead of sending a token the control plane will refuse.
+ */
+export declare function resolveTokens(stored: StoredEnvConfig, environment: Environment): ResolvedTokens;
+/**
+ * Where a command run inside a pinned directory acts: the pin's deployment,
+ * organization and environment (`--cell` takes precedence over the pin). See {@link ClientConfiguration.scopeCommand}.
+ */
+export interface CommandScope {
+    deployment: Environment;
+    organization?: string;
+    environment?: string;
+}
+export declare class ClientConfiguration {
+    /** Set once per process, before any command reads the store. */
+    private static commandScope?;
+    /**
+     * Make every default store (`new ClientConfiguration()`, the form the ~40
+     * CLI commands build for themselves) read `scope` instead of the global
+     * `activeEnvironment`, organization and environment, without writing them.
+     *
+     * The CLI calls this once at startup, for a command run in a directory
+     * `cred init` pinned, unless `--cell` names another cell: that
+     * cell's own store applies, and the pin is ignored. Without it those commands read only `~/.cred`, so in
+     * a directory pinned to one organization `cred ls connections` listed
+     * another's, and `cred rm connection` would have deleted from it.
+     *
+     * A store built with an explicit path or deployment is left alone: those
+     * are the callers that already chose where to read, and the specs.
+     */
+    static scopeCommand(scope: CommandScope | undefined): void;
+    private configPath;
+    private config;
+    private environmentOverride?;
+    private scope?;
+    /**
+     * @param customConfigPath an alternate `~/.cred` location, for tests.
+     * @param environmentOverride pin every per-environment read to this
+     *        deployment instead of the file's `activeEnvironment`, without
+     *        writing to disk. `~/.cred` stores credentials per deployment, so a
+     *        caller that targets a deployment other than the active one needs
+     *        its token, organization and environment from that deployment too:
+     *        resolving only the URL would talk to one deployment's control plane
+     *        with another's token.
+     */
+    constructor(customConfigPath?: string, environmentOverride?: Environment);
+    /**
+     * The same file, with every per-deployment read and write pinned to
+     * `environment` — the one this store resolves to now. For an operation that
+     * reads, waits and then writes: without the pin, the write resolves the
+     * deployment again and follows an `activeEnvironment` changed in between.
+     */
+    pinnedToCurrentEnvironment(): ClientConfiguration;
+    /** The same file, with every per-deployment read and write pinned to `environment`. */
+    pinnedTo(environment: Environment): ClientConfiguration;
+    /** Where this store lives on disk. The token refresh locks a file beside it. */
+    getConfigPath(): string;
+    loadConfig(): ConfigFile;
+    /**
+     * Ensure `.cred` is usable, recovering from a corrupt file if needed.
+     *
+     * `loadConfig` deliberately fails loud on a corrupt/invalid file so a read
+     * path never silently erases tokens. But `cred login` exists precisely to
+     * (re)establish config, so it must be able to get past a bad file — that is
+     * what the "re-run `cred login` to reset" message promises. We make the
+     * message true here: the bad file is renamed aside (never deleted, so a
+     * support engineer can still inspect it) and a fresh default is written.
+     *
+     * Only an {@link InvalidConfigError} triggers recovery. fs errors such as
+     * EACCES are real environment problems and are rethrown — resetting would
+     * just fail to write anyway, and we must not mask a permissions issue as a
+     * successful reset.
+     *
+     * @returns the path the corrupt file was backed up to, or null if the
+     *          existing config was already valid. The caller decides how to
+     *          report it; this module does not own a logger.
+     */
+    recoverIfCorrupt(): string | null;
+    private defaultConfig;
+    private writeConfig;
+    private currentEnvConfig;
+    setOrganization(organizationName: string): void;
+    setProject(projectName: string | undefined): void;
+    getOrganization(): string;
+    getProject(): string;
+    setAccessToken(userToken: boolean, accessToken: string): void;
+    /**
+     * Persist a freshly-issued Auth0 token pair.
+     *
+     * Writes the access token to BOTH `accessToken` and `jwtAccessToken`, which
+     * is the shape the CLI has always written and the shape the extension can
+     * still read (it takes the access token from `jwtAccessToken`). `idToken`
+     * gets its own field so it is never confused with the access token again.
+     */
+    setTokenPair(tokens: {
+        accessToken: string;
+        idToken?: string;
+        refreshToken?: string;
+    }): void;
+    /**
+     * The token to put in an `Authorization` header, resolved by audience rather
+     * than by field name so it is correct whichever tool wrote the file last.
+     */
+    getApiAccessToken(): string | undefined;
+    getIdToken(): string | undefined;
+    getAuthenticationHeader(): string;
+    /**
+     * @deprecated Ambiguous — returns the raw `accessToken` field, whose meaning
+     * depends on which tool wrote it last. Use {@link getApiAccessToken} for an
+     * `Authorization` header or {@link getIdToken} for profile claims.
+     */
+    getAccessToken(): string;
+    setJwtAccessToken(jwtAccessToken: string): void;
+    getJwtAccessToken(): string | undefined;
+    setVSCodeUser(username: string, email: string): void;
+    getVSCodeUser(): {
+        username: string;
+        email: string;
+    } | undefined;
+    setRefreshToken(refreshToken: string): void;
+    getRefreshToken(): string | undefined;
+    isServiceAccountToken(): boolean;
+    doesConfigExists(): boolean;
+    getHeaders(): {
+        Authorization: string;
+    };
+    /**
+     * Remove this deployment's tokens and keep the rest of its entry: the
+     * organization and environment (`project`) the user chose. For a session
+     * Auth0 has refused, where the next step is signing back in to the same
+     * place. `cred logout` uses `destroyConfig`, which forgets everything.
+     */
+    clearTokens(): void;
+    destroyConfig(): void;
+    setEnvironment(environment: Environment): void;
+    getEnvironment(): Environment;
+    /** The `activeEnvironment` the file records, whatever `--cell` or a pin says this store acts on. */
+    getGlobalEnvironment(): Environment;
+    /** The cells whose slot holds a token, in the order the file lists them. */
+    signedInCells(): Environment[];
+    /**
+     * Seconds until the API access token expires; negative once it has. Returns
+     * `undefined` when there is no decodable expiry — a service-account token or
+     * a malformed one — so callers can tell "no deadline" from "expires soon".
+     */
+    secondsUntilExpiry(): number | undefined;
+    isTokenValid(): {
+        valid: boolean;
+        reason?: string;
+    };
+}

package/dist/setup-core/environments.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Deployment-environment tables: which control plane, which Auth0 tenant, and
+ * which cluster each deployment env lives on.
+ *
+ * These live in setup-core rather than in the CLI's `constants.ts` because both
+ * front doors need them: the credential store keys `~/.cred` by deployment env,
+ * and token refresh needs the Auth0 domain and client id for the env it is
+ * refreshing. `constants.ts` re-exports them, so existing CLI imports are
+ * unchanged.
+ *
+ * DELIBERATELY NO SECRETS HERE. The `e2e-test` machine-to-machine client secret
+ * stays in the CLI's `constants.ts`, where its single consumer (`loginM2M`)
+ * lives. setup-core is destined to be a published library; a credential in it
+ * would be shipped to every consumer of that library.
+ *
+ * Note the naming collision this file inherits and does not fix: `Environment`
+ * here is the DEPLOYMENT env (production/staging/dev/localhost), an internal
+ * axis. The user-facing "environment" is the Credible environment inside an
+ * organization, which the store calls `project` for legacy reasons.
+ */
+export type Environment = "production" | "staging" | "dev" | "localhost" | "e2e-test" | "videoamp" | "aws-dev" | "aws-dev-2" | "aws-affinity";
+export declare const controlPlanesByEnv: Record<Environment, string>;
+/**
+ * The app per deployment, without the organization. Organizations are a
+ * subdomain (`<org>.<host>`), as `getOrganizationUrl` builds it in
+ * `app/src/components/Utils.ts`; see {@link packageVersionUrl}.
+ */
+export declare const appHostsByEnv: Record<Environment, string>;
+/**
+ * Where a published version opens in the app: the `/:project/:package/:version`
+ * route in `app/src/AdminApp.tsx`, on the organization's own subdomain.
+ */
+export declare function packageVersionUrl(deployment: Environment, organization: string, environment: string, packageName: string, versionId: string): string;
+/**
+ * The code-assist API per deployment, for the skills installer. Keyed off
+ * {@link Environment} like the other host tables, so adding a deployment
+ * without a host here fails the build rather than falling through to
+ * production. Values are the ones the VS Code extension ships in
+ * `src/config/public/<env>.json`.
+ */
+export declare const codeAssistByEnv: Record<Environment, string>;
+/** Environments that must have an object in `~/.cred` `configPerEnvironment` (avoids undefined on write). */
+export declare const ALL_ENVIRONMENTS: Environment[];
+/**
+ * The deployment env everything falls back to.
+ *
+ * Named because two places have to agree on it and neither is obviously the
+ * authority: it is what a fresh `~/.cred` records as `activeEnvironment`, and it
+ * is what a folder pin with no `deployment` means (earlier builds left it out
+ * for this value; see `resolveDeployment`).
+ */
+export declare const DEFAULT_DEPLOYMENT: Environment;
+/** Is `value` one of the deployment envs this build knows about? */
+export declare function isEnvironment(value: unknown): value is Environment;
+/**
+ * Public Auth0 parameters per deployment env. All three fields are public by
+ * construction: `clientId` and `audience` travel in every `/authorize` URL, and
+ * `domain` is the tenant hostname.
+ */
+export interface Auth0EnvConfig {
+    domain: string;
+    clientId: string;
+    audience: string;
+}
+export declare const auth0ConfigsByEnv: Record<Environment, Auth0EnvConfig>;
+/** Clusters a CLI org can target via `cred login <org> -c <cluster>`. */
+export type Cluster = "gcp" | "aws";
+/** Which cluster each {@link Environment} lives on. */
+export declare const CLUSTER_BY_ENVIRONMENT: Record<Environment, Cluster>;
+/**
+ * Default {@link Environment} to switch to when logging into a cluster and the
+ * current active env is on a different cluster. Picked per cluster so that
+ * `cred login <org> -c aws` flips to videoamp and `-c gcp` flips to production.
+ */
+export declare const DEFAULT_ENVIRONMENT_BY_CLUSTER: Record<Cluster, Environment>;
+/**
+ * Per-org CLI login config. One row per org that needs non-default behavior
+ * (multi-cluster support, Auth0 Organizations PKCE, etc.). Orgs not listed here
+ * fall back to: gcp cluster only, Device Authorization Flow, no Auth0 org id.
+ *
+ * Auth0 docs: `organization` is supported on `/authorize` for Organizations
+ * (https://auth0.com/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api)
+ * but NOT on `POST /oauth/device/code`
+ * (https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow#device-code-parameters),
+ * so orgs with an `auth0OrganizationIds` entry for the active cluster use Auth
+ * Code + PKCE via the CLI's loopback redirect URI. Keep aligned with the app's
+ * `ORGANIZATION_HOST_ORG_ID_MAP` / `getAuth0OrganizationAuthorizationParams`.
+ */
+export interface CliOrgConfig {
+    /** Lowercase CLI org name (what the user types after `cred login`). */
+    cliOrgName: string;
+    /** Clusters this org can be logged into. */
+    supportedClusters: Cluster[];
+    /** Cluster used when `-c/--cluster` is omitted. Must be in `supportedClusters`. */
+    defaultCluster: Cluster;
+    /**
+     * Auth0 Organization ID per cluster. Presence triggers the PKCE + `organization=<id>`
+     * `/authorize` flow on that cluster; absence falls back to Device Authorization Flow.
+     */
+    auth0OrganizationIds?: Partial<Record<Cluster, string>>;
+}
+/** Returns the registry entry for an org, or `undefined` if it uses defaults (gcp + device flow). */
+export declare function getCliOrgConfig(organizationName: string): CliOrgConfig | undefined;
+/**
+ * Auth0 Organization ID for the given CLI org on the cluster it is logging into.
+ * Returning a value selects the Auth Code + PKCE branch in `login()`; `undefined`
+ * falls back to Device Authorization Flow.
+ *
+ * `cluster` defaults to the org's `defaultCluster` (or `gcp` for unregistered orgs)
+ * so callers that don't yet know the active cluster keep working.
+ */
+export declare function getAuth0OrganizationIdForCliLogin(organizationName: string, cluster?: Cluster): string | undefined;

package/dist/setup-core/flow.d.ts

@@ -0,0 +1,171 @@
+import { ClientConfiguration } from "./credstore";
+import { Environment } from "./environments";
+import { ConnectionCreator, ConnectionSelection } from "./importconnections";
+import { Host } from "./host";
+import { CredibleConnection, PublisherConfig } from "./publisherconfig";
+import { SkillsFetcher, SkillsPolicy } from "./skills";
+import { RunningPublisher } from "./supervisor";
+/**
+ * The setup flow itself: the six steps both front doors run.
+ *
+ * Nothing here knows whether it is talking to a terminal or to VS Code — that is
+ * the {@link Host}'s job — and nothing here parses arguments or prints. The end
+ * state on disk is therefore identical whichever front door ran it, which is the
+ * point of having one flow rather than two implementations.
+ */
+/** The one thing setup needs from the control plane, injected so it can be faked. */
+export type ConnectionLister = (organization: string, credibleEnvironment: string) => Promise<CredibleConnection[]>;
+export interface FlowContext {
+    host: Host;
+    credStore: ClientConfiguration;
+    listConnections: ConnectionLister;
+    /**
+     * Create a connection in Credible, or test one with `dryRun`.
+     *
+     * Optional: a front door that cannot create connections simply does not offer
+     * the import, rather than offering it and failing at the last step.
+     */
+    createConnection?: ConnectionCreator;
+    /**
+     * Fetch the modeling skills from code-assist.
+     *
+     * Optional for the same reason as `createConnection`: a front door without
+     * access to that API skips the step instead of offering it and failing.
+     */
+    fetchSkills?: SkillsFetcher;
+    deployment: Environment;
+    publisherVersion: string;
+    cwd: string;
+    /**
+     * Stream all of the server's output to the terminal, as `--debug` asks.
+     * Otherwise only its errors are shown, and the rest goes to its log file.
+     */
+    showAllPublisherOutput?: boolean;
+}
+export interface SetupOptions {
+    /** Wire this directory instead of the one setup was run in. */
+    directory?: string;
+    /**
+     * Which organization and Credible environment to wire this directory to.
+     *
+     * Passed in, never read from the credential store here. The store holds one
+     * organization and environment per *deployment*, so a flow that read them
+     * itself could only ever wire every directory to the same pair — which is
+     * exactly what it used to do, leaving the directory's own pin decorative.
+     * Resolving them is the front door's job (`resolveIdentity`), so the
+     * precedence between a flag, the pin and the global value is decided once.
+     */
+    organization: string;
+    credibleEnvironment: string;
+    /**
+     * Do not offer to adopt a local `publisher.config.json`.
+     *
+     * `cred dev` sets this: the offer belongs to the once-per-directory command,
+     * and re-asking every session would be nagging about a decision already made.
+     */
+    skipConnectionImport?: boolean;
+    /**
+     * Which local connections to import, when already decided (`--connections`).
+     * Absent means ask, which a host without a terminal refuses with the flag.
+     */
+    connections?: ConnectionSelection;
+    /**
+     * What to do with skills already in `.claude/skills/` that setup did not
+     * install (`--skills`, on `init` and `dev`). Absent means the pin's earlier
+     * `none`, else ask — only on a first install that finds some; later runs
+     * keep whatever is there.
+     */
+    skills?: SkillsPolicy;
+    /**
+     * Which listed package to serve, relative to the directory (`--package`),
+     * in a workspace whose `publisher.config.json` lists several. Absent means
+     * the pin's choice, else the only one, else ask.
+     */
+    package?: string;
+    /**
+     * The UI port to serve on (`--port`); MCP takes the port 40 above it.
+     * Remembered, and it wins over the remembered pair. Absent means the
+     * remembered pair, else 4000/4040, else one derived from the directory.
+     */
+    port?: number;
+    /** Write the files but do not start a server. */
+    start: boolean;
+    /** Start a server but do not open a browser. */
+    open: boolean;
+}
+export interface WiredDirectory {
+    /** The workspace: where `.mcp.json`, the briefing, the skills and the pin go. */
+    directory: string;
+    /**
+     * The package the publisher serves. Usually `directory`; for a Publisher
+     * server directory (a `publisher.config.json` listing packages, as
+     * `create-malloy-package` lays out), the package it lists.
+     */
+    packageDir: string;
+    organization: string;
+    credibleEnvironment: string;
+    config: PublisherConfig;
+    configPath: string;
+    /** Where the server keeps its own state. Not the user's directory — see below. */
+    serverRoot: string;
+    uiPort: number;
+    mcpPort: number;
+}
+/**
+ * Is this directory's own session running — not merely something answering on
+ * its pinned port?
+ *
+ * All three must hold: the session's stamped config and pid file exist (the
+ * supervisor removes both when the server exits), the pid is alive, and the
+ * port answers. The files alone were not enough: a `kill -9`, a reboot or a
+ * closed terminal leaves them behind, and two directories wired one after the
+ * other both pin 4000/4040, so the other directory's publisher answered and
+ * this one was reported as running.
+ */
+export declare function isOwnSessionRunning(directory: string, uiPort: number): Promise<boolean>;
+/** True when `file` is older than this machine's last boot. */
+export declare function writtenBeforeBoot(file: string, now?: number): boolean;
+/**
+ * Refuse, before anything is written, the questions `cred init` could not ask.
+ *
+ * Without a terminal a question exits 2. Asked in order, the connections and
+ * skills questions came after the environment was created and selected, so an
+ * agent that stopped at the exit 2 left an empty environment behind and
+ * `~/.cred` pointing at it. Checked up front, exit 2 means nothing happened,
+ * which is what a caller re-running with the flag assumes. A misspelled
+ * `--connections` name is refused here for the same reason.
+ */
+export declare function refuseUnanswerable(directory: string, options: {
+    connections?: ConnectionSelection;
+    skills?: SkillsPolicy;
+    package?: string;
+}, interactive: boolean): void;
+/**
+ * Refuse to start beside someone else's publisher, before login and the
+ * environment lookup. Checked only inside `wireDirectory`, the refusal came
+ * after both, 25 seconds and more on a slow deployment.
+ */
+export declare function refuseBesideOtherPublisher(directory: string, port?: number): Promise<void>;
+export declare function wireDirectory(context: FlowContext, options: SetupOptions): Promise<WiredDirectory>;
+/** The flag that answers {@link resolvePackageDir}'s question. */
+export declare const PACKAGE_FLAG = "--package";
+export declare const PORT_FLAG = "--port";
+/** Step 5 and 6: start the server, and open it once it is genuinely serving. */
+export declare function startSession(context: FlowContext, wired: WiredDirectory, options: {
+    open: boolean;
+}): Promise<RunningPublisher>;
+/**
+ * The whole flow: wire, then run.
+ *
+ * Setup deliberately ends in a running server rather than a printed
+ * instruction. Every step before that is invisible plumbing the user cannot
+ * check, and the Publisher UI is the first artifact that proves the whole chain
+ * — auth, connections, proxy, compile — is actually live. A setup that ends with
+ * "now run `cred dev`" ends on an unverified claim.
+ */
+export declare function runSetup(context: FlowContext, options: SetupOptions): Promise<{
+    wired: WiredDirectory;
+    running?: RunningPublisher;
+}>;
+/** "a", "a and b", "a, b and c". */
+export declare function joinNames(names: string[]): string;

package/dist/setup-core/flow.js

@@ -226,14 +226,14 @@ function otherPublisherError(free) {
 /** The flag that moves this directory to a free pair, with the pair to pass. */
 function portFix(free) {
     return free
-        ? `re-run with ${exports.PORT_FLAG} ${free.uiPort} (free now; MCP takes ${free.mcpPort}). cred remembers it and points .mcp.json there.`
-        : `re-run with ${exports.PORT_FLAG} <port>, a port that is free along with the one 40 above it. cred remembers it and points .mcp.json there.`;
+        ? `re-run with ${exports.PORT_FLAG} ${free.uiPort} (free now; MCP takes ${free.mcpPort}). cred remembers it.`
+        : `re-run with ${exports.PORT_FLAG} <port>, a port that is free along with the one 40 above it. cred remembers it.`;
 }
 /**
  * Whether someone else's publisher holds the default pair this directory would
  * use: in the "I already run a publisher" journey, the user's own, started from
- * this same directory. Moving to a derived pair rewrote `.mcp.json` away from
- * the one server the agent could reach. Not this directory's own session; the
+ * this same directory. Moving to a derived pair left the agent on a port
+ * nothing served until `cred dev`. Not this directory's own session; the
  * caller checks that first.
  */
 function otherPublisherOnDefaults(directory, pinnedPorts) {
@@ -301,16 +301,15 @@ function wireDirectory(context, options) {
         // port pair, and compared against `findFolderConfig`'s always-absolute
         // `root` to find the ports this directory used last. A relative
         // `--directory` reached all three as a different string, so `cred init -d
-        // sub` re-derived its ports every run and rewrote `.mcp.json` with a URL the
-        // agent's saved config no longer matched. Everything downstream can then
-        // treat it as absolute.
+        // sub` re-derived its ports every run, so the Publisher's address moved
+        // between runs. Everything downstream can then treat it as absolute.
         const directory = path_1.default.resolve((_a = options.directory) !== null && _a !== void 0 ? _a : context.cwd);
         const remembered = (0, folderconfig_1.findFolderConfig)(directory);
         const pinned = (remembered === null || remembered === void 0 ? void 0 : remembered.root) === directory ? remembered.config : undefined;
         // A second session for the same directory would find the pinned ports busy
-        // — held by the first — fall through to another pair, rewrite `.mcp.json`
-        // to it and start a second server, leaving the first serving on the URL any
-        // open agent still has.
+        // — held by the first — fall through to another pair, move the pin to it
+        // and start a second server, leaving the first serving where any open
+        // agent's `cred mcp` is connected.
         const ownSessionRunning = Boolean((pinned === null || pinned === void 0 ? void 0 : pinned.ports) &&
             (yield isOwnSessionRunning(directory, pinned.ports.uiPort)));
         if (options.start && ownSessionRunning) {
@@ -318,9 +317,9 @@ function wireDirectory(context, options) {
         }
         // Someone else's publisher on the default pair — in the "I already run a
         // publisher" journey, the user's own, started from this same directory.
-        // Moving to a derived pair rewrote `.mcp.json` away from the one server the
-        // agent could reach, to a port nothing served until `cred dev`. Staying on
-        // the default pair keeps that URL; the old server has to stop first.
+        // Moving to a derived pair left the agent on a port nothing served until
+        // `cred dev`. Staying on the default pair keeps the address; the old server
+        // has to stop first.
         const otherPublisher = options.port === undefined &&
             !ownSessionRunning &&
             (yield otherPublisherOnDefaults(directory, pinned === null || pinned === void 0 ? void 0 : pinned.ports));
@@ -388,11 +387,11 @@ function wireDirectory(context, options) {
             environmentName: (0, publisherconfig_1.localEnvironmentName)(credibleEnvironment),
             retrieval: retrieval && "settings" in retrieval ? retrieval.settings : undefined,
         });
-        // Reuse this directory's remembered ports so an agent's saved `.mcp.json` URL
-        // keeps resolving across sessions. While this directory's own session holds
-        // them (`--no-start` beside a running `cred dev`) they are busy because they
-        // are in use, so they are kept rather than probed: probing found them busy
-        // and moved `.mcp.json` to a pair nothing was listening on.
+        // Reuse this directory's remembered ports so the Publisher keeps one address
+        // across sessions. While this directory's own session holds them
+        // (`--no-start` beside a running `cred dev`) they are busy because they are
+        // in use, so they are kept rather than probed: probing found them busy and
+        // moved the directory to a pair nothing was listening on.
         const ports = options.port !== undefined
             ? yield chosenPair(directory, options.port, {
                 ownSessionRunning,
@@ -412,7 +411,6 @@ function wireDirectory(context, options) {
         const configPath = sessionConfigPath(directory);
         const mcp = (0, mcpconfig_1.writeMcpConfig)({
             directory,
-            mcpPort: ports.mcpPort,
             deployment: context.deployment,
             organization,
         });
@@ -438,7 +436,7 @@ function wireDirectory(context, options) {
             // rewrites nothing and this line would be noise.
             context.host.log("info", `Wrote .mcp.json. An agent already running in this directory will not see the new MCP servers until it restarts — for Claude Code, exit and start \`claude\` here again; it asks once to trust the project's servers.`);
         }
-        (0, briefing_1.writeBriefing)(directory, {
+        const briefing = (0, briefing_1.writeBriefing)(directory, {
             organization,
             credibleEnvironment,
             localEnvironment: config.environments[0].name,
@@ -482,7 +480,35 @@ function wireDirectory(context, options) {
         // The pin is this developer's choice of environment, not a property of the
         // models, so a teammate must not inherit it by cloning.
         if ((0, folderconfig_1.ensureConfigIgnored)(directory) === "added") {
-            context.host.log("info", `Added ${folderconfig_1.FOLDER_CONFIG_DIR}/ to .gitignore — it records the environment you chose, which is yours rather than the repository's.`);
+            context.host.log("info", `Added ${folderconfig_1.FOLDER_CONFIG_DIR}/ to .git/info/exclude — it records the environment you chose, which is yours rather than the repository's.`);
+        }
+        // Agent files that hold nothing but what setup wrote are regenerated by
+        // every run, so they stay out of git like the pin. A file the repository
+        // tracks cannot be excluded, and one holding the user's own content is
+        // theirs to commit or not.
+        const agentFiles = [
+            ...(mcp.onlyOurs ? [mcpconfig_1.MCP_CONFIG_FILENAME] : []),
+            ...briefing
+                .filter((file) => file.onlyOurs)
+                .map((file) => path_1.default.basename(file.filePath)),
+        ].filter((file) => !(0, git_1.isTrackedByGit)(directory, file));
+        (0, folderconfig_1.ensureIgnored)(directory, agentFiles, "agent files cred init writes; re-run it to regenerate them");
+        // A file an earlier run excluded that now holds the user's own content
+        // is theirs again, so git must show it.
+        (0, folderconfig_1.removeIgnored)(directory, [
+            ...(mcp.onlyOurs ? [] : [mcpconfig_1.MCP_CONFIG_FILENAME]),
+            ...briefing
+                .filter((file) => !file.onlyOurs)
+                .map((file) => path_1.default.basename(file.filePath)),
+        ]);
+        const trackedAndChanged = [
+            ...(mcp.changed ? [mcpconfig_1.MCP_CONFIG_FILENAME] : []),
+            ...briefing
+                .filter((file) => file.action !== "unchanged")
+                .map((file) => path_1.default.basename(file.filePath)),
+        ].filter((file) => (0, git_1.isTrackedByGit)(directory, file));
+        if (trackedAndChanged.length) {
+            context.host.log("info", `Updated what Credible manages in ${joinNames(trackedAndChanged)}, which git tracks, so it shows as a change to commit or discard.`);
         }
         if (skills) {
             // Installer-managed files, regenerated by every setup and pinned in a
@@ -583,12 +609,12 @@ exports.PORT_FLAG = "--port";
  * The pair `--port` names, refused when something else holds it.
  *
  * Unlike the remembered pair, which quietly gives way to another when busy, a
- * chosen pair is used as given or not at all: moving off it would point
- * `.mcp.json` somewhere the user did not ask for. This directory's own running
- * session holding it is not a conflict (`--no-start` beside `cred dev`). That
- * session running on a different pair is: moving the pin and `.mcp.json` away
- * from the live server leaves the agent's URL pointing at nothing, and the
- * next ownership check would miss the running server.
+ * chosen pair is used as given or not at all: moving off it would serve
+ * somewhere the user did not ask for. This directory's own running session
+ * holding it is not a conflict (`--no-start` beside `cred dev`). That session
+ * running on a different pair is: moving the pin away from the live server
+ * means `cred mcp`, which finds the server through the pin, and the next
+ * ownership check would both miss it.
  */
 function chosenPair(directory, uiPort, own) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -749,7 +775,7 @@ function runSetup(context, options) {
             context.host.log("info", 
             // The last line an agent sees, so it repeats the restart: the agent
             // that ran this has no `malloy` tools until it starts again.
-            `Wired ${wired.directory}. Next: restart any agent session in that directory so it loads .mcp.json, then run \`cred dev\` there to start the publisher.`);
+            `Wired ${wired.directory}. Next: restart any agent session in that directory so it loads .mcp.json; its \`malloy\` server starts the publisher through \`cred mcp\`. Without an agent, run \`cred dev\` there.`);
             return { wired };
         }
         const running = yield startSession(context, wired, { open: options.open });