@credibledata/cred-cli 0.0.103 → 0.0.105

package/README.md

@@ -8,4 +8,109 @@ This directory contains a simple CLI to create, update, delete, and list project
 
 For complete usage instructions and command reference, see the official documentation at [https://www.credibledata.com/docs/platform-admin/cli](https://www.credibledata.com/docs/platform-admin/cli).
 
-```
+### Driving `cred` from an agent
+
+`cred` is built to be run by a coding agent (Claude Code, Codex, Cursor) as well
+as by a person. The contract:
+
+- **Every question has a flag.** A picker is the human way to answer it; the
+  flag is the other way — `cred login <organization>` answers the organization
+  picker, `cred publish --yes` answers the publish confirmation, and
+  `cred init -o <org> -e <env> [--create-environment]
+  [--connections all|none|a,b] [--skills replace|keep|none] [--package <dir>]
+  --no-start --no-open` runs the whole setup with no prompt.
+- **Without a terminal, nothing prompts.** When stdin is not a TTY, `CI` or
+  `CRED_NON_INTERACTIVE` is set (to anything but `0` or `false`), or
+  `--non-interactive` is passed, a command that needs an answer exits **2**
+  and prints the flag and the options on stderr, e.g.
+  `Cannot ask "Which environment?" without a terminal. Pass --environment <name>. Options: prod-bars, staging.`
+  Exit 0 is success, 1 is failure, 2 is "needs input".
+- **The update notice can be turned off.** When a newer `cred` is on npm, commands
+  print one line on stderr saying so. `CI`, `CRED_NO_UPDATE_CHECK`, or
+  `NO_UPDATE_NOTIFIER` set (to anything but `0` or `false`) silences it and stops
+  the once-a-day registry check.
+- **Logs go to stderr; data goes to stdout.** `cred status --json` and
+  `cred ls ...` print one JSON document you can parse. `cred status --json`
+  reports `organization` and `environment` (what `cred publish` here would act
+  on: `--cell`'s cell, else the directory's pin, else `~/.cred`), `deployment`,
+  `controlPlane`, `deploymentFrom` (`flag` when `--cell` chose the deployment,
+  `folder` when this directory's pin did, else `global`), `ignoredPin` (the pin's
+  cell, only when `--cell` names another), `token` (`valid`, `kind`,
+  `expiresInSeconds`), and in a directory `cred init` wired, `directory` (the
+  pin, with its `deployment`) and `publisher`
+  (`running`, `ready`, `packages`, `uiUrl`, `mcpUrl`) — or `{ "error": ... }`
+  with exit 1 when it cannot read your setup.
+- **Every command says where it acts, and acts where the directory is pinned.**
+  In a directory `cred init` set up, org- and environment-scoped commands
+  (`ls`, `get`, `add`, `update`, `rm`, `publish`) use the directory's
+  deployment, organization and environment; elsewhere, `~/.cred`'s. Each prints
+  `Using <org>/<env> on <cell>, pinned in .credible/config.json.` (or
+  `set by --cell`, or `from your global settings`) on stderr, and every
+  confirmation repeats it. The cell is always named.
+  An agent should check that line before anything that changes state.
+  `cred set environment` and `cred set cell <cell>` always change the global
+  settings; `cred --cell <cell> init` re-pins a directory. `--cell` naming another cell than the pin makes reads act
+  on that cell, and makes writes (`publish`, `add connection`) and `cred dev`
+  refuse; `cred --cell <cell> init` is the explicit re-pin.
+- **`cred publish` can be previewed and read back.** `--dry-run` lists the
+  files it would upload (stdout) and the ones it leaves out (stderr), uploads
+  nothing and needs no login. `--json` prints one document: `organization`,
+  `environment`, `package`, `version`, `url` (the version in the app),
+  `latest` (`now`, `when-built` or `no`), `latestVersion`, `excluded` and
+  `response` (the server's reply as sent). With `--dry-run`, `--json` prints
+  `dryRun` (`true`), `package`, `version`, `included` and `excluded` instead.
+  A `.credignore` beside `publisher.json` leaves more files out,
+  one path or glob per line (`notes.md`, `tests/`, `/docs`), matched regardless
+  of case (`secrets/` also leaves out `Secrets/`). A nested `.credignore` is not
+  read, and every file or folder named `.credignore`, at any depth, is always
+  left out of the upload. It can never put back a file the fixed list leaves
+  out, and a publish stops if it leaves out `publisher.json`. Warnings the
+  server raises on the publish print on stderr after the link; with `--json`
+  they are only in `response.warnings`. `cred get version <package> <version>`
+  shows whether a version has built (`buildStatus`: `BUILDING`, then `READY`,
+  `FAILED` or `UNSUPPORTED`) and is waiting to become latest
+  (`promoteWhenReady`). Add `--wait` to read again every 10 seconds until it
+  reaches one of those three and print that; it exits 1 on `FAILED` or when
+  `--timeout <minutes>` (default 30; it needs `--wait`) runs out. `cred get package <package>`
+  shows the latest.
+- **`cred token` prints a usable access token and nothing else**, renewing it
+  first when it is within two minutes of expiring. It exits 1 rather than print
+  a token that has already expired.
+- **`cred login` needs the human once.** It prints a URL and a code; relay them
+  and wait — it polls until they sign in. Credentials are kept per cell, and
+  `--cell` is never saved: after `cred --cell staging login`, pass `--cell
+  staging` on every command or run `cred set cell staging` (the login says so
+  when your global cell differs). Already signed in to the cell, `cred login
+  <org>` only switches organization and says which cell and whether anything
+  changed; `cred login --force` signs in again, as someone else, without a
+  logout. `cred logout` signs out of one cell, the way `login` resolves it
+  (`--cell`, then the directory's pin, then the global cell), names it, and
+  leaves the other cells signed in; given a cell with nothing to clear it lists
+  the cells that hold credentials and the `cred --cell <cell> logout` to run.
+- **`cred dev` is a foreground process.** Start it in the background with
+  `--no-open`, then poll `cred status --json` until `publisher.ready` is true
+  (`running` alone can be a server whose only package failed to compile).
+- **Ports.** A directory keeps the pair it used last, else 4000/4040, else a
+  free pair derived from its path. In a directory with its own
+  `publisher.config.json`, another Publisher on 4000/4040 is refused rather
+  than stepped around, and the error names a free port. Re-run with
+  `--port <that port>` (on `init` or `dev`): MCP takes the port 40 above it,
+  the pair is remembered, and `.mcp.json` follows.
+
+The three journeys, as commands:
+
+```bash
+# 1. I run a local Publisher against my own warehouse; move to Credible.
+cred init -e my-env --create-environment --connections my_warehouse --no-start
+cred dev --no-open &          # then poll: cred status --json
+cred publish -y               # publisher.config.json is never uploaded
+
+# 2. I run a local Publisher over CSV / DuckDB files; publish the package.
+#    (a create-malloy-package directory: setup serves the package it lists,
+#     and --skills says what to do with the scaffolder's skills)
+cred init -e my-env --create-environment --connections none --skills replace --no-start
+cd shop && cred publish -y    # the data files travel inside the package
+
+# 3. I use Credible and want to model locally with Claude Code.
+cred init -e prod-bars --no-start   # skills, .mcp.json, CLAUDE.md, publisher config
+cred dev --no-open &                 # local publisher proxies to the real warehouse

package/dist/agent-contract.spec.js

@@ -0,0 +1,548 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const environments_1 = require("./setup-core/environments");
+/**
+ * The agent contract, checked against the real CLI.
+ *
+ * Every other spec exercises the guard through stubs. This one spawns the CLI
+ * with a piped stdin — exactly what an agent's shell tool gives it — and asserts
+ * the three things an agent depends on: a question it cannot answer exits 2 and
+ * names the flag; stdout of a `--json` command is one JSON document and nothing
+ * else; and a plain failure is still exit 1. No network: the cases below stop
+ * before any request.
+ */
+function jwt(claims) {
+    const part = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+    return `${part({ alg: "HS256" })}.${part(claims)}.sig`;
+}
+describe("the agent contract, against the real CLI", function () {
+    // ts-node compiles the CLI on each spawn.
+    this.timeout(90000);
+    let home;
+    let workDir;
+    beforeEach(() => {
+        home = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "cred-home-"));
+        workDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "cred-work-"));
+        fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), JSON.stringify({
+            configPerEnvironment: {
+                production: {
+                    organization: "acme",
+                    project: "prod-bars",
+                    jwtAccessToken: jwt({
+                        aud: "https://ms2data.us.auth0.com/api/v2/",
+                        exp: Math.floor(Date.now() / 1000) + 3600,
+                    }),
+                },
+            },
+            activeEnvironment: "production",
+        }));
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(home, { recursive: true, force: true });
+        fs_1.default.rmSync(workDir, { recursive: true, force: true });
+    });
+    function cred(args, env = {}) {
+        const result = (0, child_process_1.spawnSync)(process.execPath, [
+            path_1.default.join(__dirname, "..", "node_modules", "ts-node", "dist", "bin.js"),
+            "--transpile-only",
+            path_1.default.join(__dirname, "index.ts"),
+            ...args,
+        ], {
+            cwd: workDir,
+            // A pipe, not a TTY: the shape an agent's shell tool provides.
+            stdio: ["pipe", "pipe", "pipe"],
+            env: Object.assign(Object.assign(Object.assign({}, process.env), { HOME: home, CI: undefined, NO_COLOR: "1", 
+                // No registry call from a test.
+                CRED_NO_UPDATE_CHECK: "1" }), env),
+            encoding: "utf-8",
+            // The failure this spec exists to catch is a prompt waiting on a
+            // pipe forever. Without a deadline that is a hung test run, not a
+            // red one.
+            timeout: 30000,
+        });
+        if (result.signal) {
+            throw new Error(`cred ${args.join(" ")} did not exit within 30s (killed with ${result.signal}) — a prompt is waiting on a pipe. stderr so far:\n${result.stderr}`);
+        }
+        return {
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    it("status --json puts one JSON document on stdout and nothing else", () => {
+        const run = cred(["status", "--json"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+        const report = JSON.parse(run.stdout);
+        (0, chai_1.expect)(report.organization).to.equal("acme");
+        (0, chai_1.expect)(report.environment).to.equal("prod-bars");
+        (0, chai_1.expect)(report.token.valid).to.equal(true);
+        (0, chai_1.expect)(report.directory).to.equal(null);
+        (0, chai_1.expect)(report.publisher).to.equal(null);
+    });
+    describe("--cell", () => {
+        // Each cell has its own Auth0 audience, and the `sub` tells the tokens apart.
+        const token = (cell) => jwt({
+            aud: environments_1.auth0ConfigsByEnv[cell].audience,
+            sub: cell,
+            exp: Math.floor(Date.now() / 1000) + 3600,
+        });
+        beforeEach(() => {
+            const config = JSON.parse(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8"));
+            config.configPerEnvironment.staging = {
+                organization: "acme",
+                project: "stage-bars",
+                jwtAccessToken: token("staging"),
+            };
+            config.configPerEnvironment["aws-dev"] = {
+                organization: "acme",
+                project: "aws-bars",
+                jwtAccessToken: token("aws-dev"),
+            };
+            fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), JSON.stringify(config));
+        });
+        const activeEnvironment = () => JSON.parse(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8"))
+            .activeEnvironment;
+        it("names the cell before or after the subcommand, and leaves activeEnvironment alone", () => {
+            for (const args of [
+                ["--cell", "staging", "status", "--json"],
+                ["status", "--json", "--cell=staging"],
+            ]) {
+                const run = cred(args);
+                (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+                const report = JSON.parse(run.stdout);
+                (0, chai_1.expect)(report.deployment).to.equal("staging");
+                (0, chai_1.expect)(report.deploymentFrom).to.equal("flag");
+                (0, chai_1.expect)(report.environment).to.equal("stage-bars");
+            }
+            (0, chai_1.expect)(activeEnvironment()).to.equal("production");
+        });
+        it("prints the token of the cell it names", () => {
+            const run = cred(["--cell", "staging", "token"]);
+            (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+            const claims = JSON.parse(Buffer.from(run.stdout.trim().split(".")[1], "base64url").toString());
+            (0, chai_1.expect)(claims.sub).to.equal("staging");
+            (0, chai_1.expect)(activeEnvironment()).to.equal("production");
+        });
+        it("refuses a login that would land on another cell, and leaves activeEnvironment alone", () => {
+            const run = cred([
+                "--cell",
+                "staging",
+                "login",
+                "acme",
+                "-c",
+                "aws",
+                "--no-browser",
+            ]);
+            (0, chai_1.expect)(run.status, run.stdout).to.equal(1);
+            (0, chai_1.expect)(run.stderr).to.not.contain("    at ");
+            (0, chai_1.expect)(activeEnvironment()).to.equal("production");
+        });
+        it("refuses a write in a directory pinned to another cell, naming init", () => {
+            fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+            fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({ deployment: "staging", organization: "acme" }));
+            const run = cred(["--cell", "aws-dev", "publish"]);
+            (0, chai_1.expect)(run.status).to.equal(1);
+            (0, chai_1.expect)(run.stderr).to.contain("--cell aws-dev init");
+            (0, chai_1.expect)(run.stderr).to.not.contain("    at ");
+        });
+        it("refuses a write whose option value hides it from the argv heuristic", () => {
+            fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+            fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({ deployment: "staging", organization: "acme" }));
+            const run = cred([
+                "--cell",
+                "aws-dev",
+                "publish",
+                "--replication",
+                "2",
+                "--yes",
+            ]);
+            (0, chai_1.expect)(run.status).to.equal(1);
+            (0, chai_1.expect)(run.stderr).to.contain("--cell aws-dev init");
+        });
+        for (const flag of ["--help", "--dry-run"]) {
+            it(`does not refuse publish ${flag} in a directory pinned to another cell`, () => {
+                fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+                fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({ deployment: "staging", organization: "acme" }));
+                const run = cred(["--cell", "aws-dev", "publish", flag]);
+                (0, chai_1.expect)(run.stderr).to.not.contain("--cell aws-dev init");
+            });
+        }
+        describe("logout", () => {
+            const signedIn = () => {
+                const config = JSON.parse(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8"));
+                return Object.entries(config.configPerEnvironment)
+                    .filter(([, slot]) => slot.jwtAccessToken)
+                    .map(([cell]) => cell);
+            };
+            it("signs out of the cell a directory pin names, and says so", () => {
+                fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+                fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({ deployment: "aws-dev", organization: "acme" }));
+                const run = cred(["logout"]);
+                (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+                (0, chai_1.expect)(run.stderr).to.contain("Signed out of aws-dev (acme/aws-bars), pinned in .credible/config.json.");
+                (0, chai_1.expect)(signedIn()).to.have.members(["production", "staging"]);
+                (0, chai_1.expect)(activeEnvironment()).to.equal("production");
+            });
+            it("lets --cell win over the pin, and over the global cell", () => {
+                const run = cred(["--cell", "staging", "logout"]);
+                (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+                (0, chai_1.expect)(run.stderr).to.contain("Signed out of staging (acme/stage-bars), set by --cell.");
+                (0, chai_1.expect)(signedIn()).to.have.members(["production", "aws-dev"]);
+            });
+            it("lists the signed-in cells and the command when the resolved cell has nothing to clear", () => {
+                const run = cred(["--cell", "dev", "logout"]);
+                (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+                (0, chai_1.expect)(run.stderr).to.contain("Not signed in to dev");
+                (0, chai_1.expect)(run.stderr).to.contain("`cred --cell staging logout`");
+                (0, chai_1.expect)(signedIn()).to.have.members([
+                    "production",
+                    "staging",
+                    "aws-dev",
+                ]);
+            });
+        });
+        it("rejects an unknown cell without a stack trace, as JSON under status --json", () => {
+            const plain = cred(["--cell", "bogus", "status"]);
+            (0, chai_1.expect)(plain.status).to.equal(1);
+            (0, chai_1.expect)(plain.stderr)
+                .to.contain("Unknown cell")
+                .and.to.contain("aws-dev");
+            (0, chai_1.expect)(plain.stderr).to.not.contain("    at ");
+            // Before the command too: the bad value must not be read as it.
+            const before = cred(["--cell", "bogus", "status", "--json"]);
+            (0, chai_1.expect)(JSON.parse(before.stdout).error).to.contain("Unknown cell");
+            const json = cred(["status", "--json", "--cell", "bogus"]);
+            (0, chai_1.expect)(json.status).to.equal(1);
+            (0, chai_1.expect)(JSON.parse(json.stdout).error).to.contain("Unknown cell");
+        });
+        it("lets two concurrent processes each report their own cell", () => __awaiter(this, void 0, void 0, function* () {
+            const run = (cell) => new Promise((resolve, reject) => {
+                const child = (0, child_process_1.spawn)(process.execPath, [
+                    path_1.default.join(__dirname, "..", "node_modules", "ts-node", "dist", "bin.js"),
+                    "--transpile-only",
+                    path_1.default.join(__dirname, "index.ts"),
+                    "status",
+                    "--json",
+                    "--cell",
+                    cell,
+                ], {
+                    cwd: workDir,
+                    env: Object.assign(Object.assign({}, process.env), { HOME: home, CRED_NO_UPDATE_CHECK: "1" }),
+                });
+                let out = "";
+                child.stdout.on("data", (chunk) => (out += chunk));
+                child.on("error", reject);
+                child.on("close", () => resolve(JSON.parse(out).deployment));
+            });
+            (0, chai_1.expect)(yield Promise.all([run("staging"), run("aws-dev")])).to.eql([
+                "staging",
+                "aws-dev",
+            ]);
+            (0, chai_1.expect)(activeEnvironment()).to.equal("production");
+        }));
+    });
+    it("names a newer cred on stderr, leaving --json stdout alone", () => {
+        // A fresh cache, so no ask is started; under ts-node there is no compiled
+        // worker to start one anyway.
+        fs_1.default.mkdirSync(path_1.default.join(home, ".credible"));
+        fs_1.default.writeFileSync(path_1.default.join(home, ".credible", "version-check.json"), JSON.stringify({ checkedAt: Date.now(), latest: "999.0.0" }));
+        const run = cred(["status", "--json"], {
+            CRED_NO_UPDATE_CHECK: undefined,
+            NO_UPDATE_NOTIFIER: undefined,
+        });
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+        (0, chai_1.expect)(run.stderr).to.contain("999.0.0 is available. Update: npm i -g @credibledata/cred-cli@latest");
+        (0, chai_1.expect)(JSON.parse(run.stdout).organization).to.equal("acme");
+    });
+    // A corrupt ~/.cred is what a caller runs `status` to find out about. The
+    // file is read at startup, before Commander parses anything, so without the
+    // startup guard this was a stack trace and an empty stdout.
+    it("status --json answers a corrupt ~/.cred with a JSON error", () => {
+        fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), "{ not json");
+        const run = cred(["status", "--json"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(1);
+        const report = JSON.parse(run.stdout);
+        (0, chai_1.expect)(report.error).to.contain("cred login");
+        (0, chai_1.expect)(run.stderr).to.not.contain("    at ");
+    });
+    // The confirmation is the cheapest real prompt to reach: `cred publish`
+    // refuses it before any network call, so this exercises the whole path — a
+    // real spawn, a real pipe, `NeedsInputError`, exit 2, the flag on stderr —
+    // without a control plane.
+    it("a question it cannot ask exits 2 and names the flag", () => {
+        fs_1.default.writeFileSync(path_1.default.join(workDir, "publisher.json"), JSON.stringify({ name: "bars", version: "0.0.1" }));
+        const run = cred(["publish"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(2);
+        (0, chai_1.expect)(run.stderr).to.contain("--yes");
+        (0, chai_1.expect)(run.stderr).to.contain("without a terminal");
+        (0, chai_1.expect)(run.stdout).to.equal("");
+    });
+    // The preHook skips the session refresh for a dry run. Without that skip it
+    // demanded a login before the preview, which needs none.
+    it("publish --dry-run and add version --dry-run work with no login", () => {
+        fs_1.default.rmSync(path_1.default.join(home, ".cred"));
+        fs_1.default.writeFileSync(path_1.default.join(workDir, "publisher.json"), JSON.stringify({ name: "bars", version: "0.0.1" }));
+        for (const command of [["publish"], ["add", "version"]]) {
+            const run = cred([...command, "--dry-run"]);
+            (0, chai_1.expect)(run.status, `${command.join(" ")}: ${run.stderr}`).to.equal(0);
+            (0, chai_1.expect)(run.stdout.trim(), command.join(" ")).to.equal("publisher.json");
+        }
+    });
+    it("a picker it cannot show exits 2 and names the flag and the options", () => {
+        fs_1.default.writeFileSync(path_1.default.join(workDir, "publisher.config.json"), JSON.stringify({
+            connections: [
+                {
+                    name: "warehouse",
+                    type: "postgres",
+                    postgresConnection: { host: "db", password: "hunter2" },
+                },
+                { name: "other", type: "postgres", postgresConnection: {} },
+            ],
+        }));
+        const run = cred(["add", "connection", "--from-publisher-config"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(2);
+        // This command's own flag. `--connections` is `cred init`'s, and
+        // following it here was an unknown-option error.
+        (0, chai_1.expect)(run.stderr).to.contain("Pass --name <connection> (once per connection).");
+        (0, chai_1.expect)(run.stderr).to.contain("Options: warehouse, other.");
+        (0, chai_1.expect)(run.stderr, "a credential never reaches the terminal").to.not.contain("hunter2");
+        (0, chai_1.expect)(run.stdout).to.equal("");
+    });
+    it("a plain failure is still exit 1, with the fix on stderr", () => {
+        const run = cred(["dev", "--no-open"]);
+        (0, chai_1.expect)(run.status).to.equal(1);
+        (0, chai_1.expect)(run.stderr).to.contain("Run `cred init` here first");
+    });
+    // These guards printed their error and exited 0, so a script read
+    // `get version --wait` with no environment set as a version that was READY.
+    it("a command that needs an environment exits 1 when none is set, with nothing on stdout", () => {
+        const config = JSON.parse(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8"));
+        delete config.configPerEnvironment.production.project;
+        fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), JSON.stringify(config));
+        for (const args of [
+            ["get", "version", "bars", "0.0.1", "--wait"],
+            ["get", "run", "bars", "run-1"],
+            ["ls", "versions", "bars"],
+            ["ls", "connections"],
+        ]) {
+            const run = cred(args);
+            (0, chai_1.expect)(run.status, `cred ${args.join(" ")}: ${run.stderr}`).to.equal(1);
+            (0, chai_1.expect)(run.stderr).to.contain("Please, make sure to set an environment");
+            (0, chai_1.expect)(run.stdout).to.equal("");
+        }
+    });
+    // `debugRequested` reads argv directly, so a unit test cannot tell whether
+    // Commander accepts the flag the startup line tells the user to pass.
+    it("init and dev accept the --debug their startup line names", () => {
+        const dev = cred(["dev", "--no-open", "--debug"]);
+        (0, chai_1.expect)(dev.stderr).to.not.contain("unknown option");
+        (0, chai_1.expect)(dev.stderr).to.contain("Run `cred init` here first");
+        const init = cred(["init", "--no-start", "--no-open", "--debug"]);
+        (0, chai_1.expect)(init.stderr).to.not.contain("unknown option");
+    });
+    it("init refuses an unanswerable question before it writes anything", () => {
+        fs_1.default.writeFileSync(path_1.default.join(workDir, "publisher.config.json"), JSON.stringify({
+            connections: [
+                { name: "warehouse", type: "postgres", postgresConnection: {} },
+            ],
+        }));
+        const before = fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8");
+        const run = cred(["init", "--no-start", "--no-open"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(2);
+        (0, chai_1.expect)(run.stderr).to.contain("Pass --connections <all|none|name,name>.");
+        (0, chai_1.expect)(fs_1.default.readdirSync(workDir)).to.eql(["publisher.config.json"]);
+        (0, chai_1.expect)(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8")).to.equal(before);
+    });
+    // A value the flag does not accept is a usage error, so it exits 2 like the
+    // prompts above, not 1 like a run that failed. The fix hint stays.
+    it("an invalid --skills or --timeout value exits 2 with the fix on stderr", () => {
+        const skills = cred([
+            "init",
+            "--no-start",
+            "--no-open",
+            "--skills",
+            "bogus",
+        ]);
+        (0, chai_1.expect)(skills.status, skills.stderr).to.equal(2);
+        (0, chai_1.expect)(skills.stderr).to.contain("--skills <replace|keep|none> was given 'bogus'.");
+        (0, chai_1.expect)(skills.stderr).to.contain("Fix: pass replace, keep, or none.");
+        (0, chai_1.expect)(skills.stdout).to.equal("");
+        const timeout = cred([
+            "get",
+            "version",
+            "bars",
+            "0.0.1",
+            "--wait",
+            "--timeout",
+            "abc",
+        ]);
+        (0, chai_1.expect)(timeout.status, timeout.stderr).to.equal(2);
+        (0, chai_1.expect)(timeout.stderr).to.contain("Invalid --timeout 'abc': expected a number of minutes above 0. Fix: --timeout 30");
+        // Without --wait, --timeout would be ignored, valid value or not.
+        const unwaited = cred([
+            "get",
+            "version",
+            "bars",
+            "0.0.1",
+            "--timeout",
+            "5",
+        ]);
+        (0, chai_1.expect)(unwaited.status, unwaited.stderr).to.equal(2);
+        (0, chai_1.expect)(unwaited.stderr).to.contain("--timeout only applies with --wait. Fix: add --wait, or drop --timeout.");
+        (0, chai_1.expect)(unwaited.stdout).to.equal("");
+    });
+    // The refresh before a command has to renew the login the command will
+    // send. `add version` runs publish's action, and checking the global login
+    // for it failed with "not logged in" in a directory whose own was fine.
+    it("refreshes the pinned deployment's login for publish and add version", () => {
+        fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), JSON.stringify({
+            configPerEnvironment: {
+                staging: {
+                    organization: "acme",
+                    project: "prod-bars",
+                    jwtAccessToken: jwt({
+                        aud: "https://dev-ohaafogw5p8uyx1m.us.auth0.com/api/v2/",
+                        exp: Math.floor(Date.now() / 1000) + 3600,
+                    }),
+                },
+            },
+            activeEnvironment: "production",
+        }));
+        fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+        fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({
+            deployment: "staging",
+            organization: "acme",
+            environment: "prod-bars",
+        }));
+        for (const command of [["publish"], ["add", "version"]]) {
+            const run = cred([...command, "--yes"]);
+            (0, chai_1.expect)(run.stderr, command.join(" ")).to.not.contain("not logged in");
+            (0, chai_1.expect)(run.stderr, command.join(" ")).to.contain("Publishing to acme/prod-bars on staging");
+        }
+    });
+    // Every org- and environment-scoped command acts on the pin, as publish
+    // does. They read only ~/.cred, so in a directory pinned to acme a
+    // `cred rm connection` would have deleted from the global organization.
+    it("acts on the pinned organization for every scoped command, and names it in the question", () => {
+        fs_1.default.writeFileSync(path_1.default.join(home, ".cred"), JSON.stringify({
+            configPerEnvironment: {
+                production: {
+                    organization: "global-org",
+                    project: "global-env",
+                    jwtAccessToken: jwt({
+                        aud: "https://ms2data.us.auth0.com/api/v2/",
+                        exp: Math.floor(Date.now() / 1000) + 3600,
+                    }),
+                },
+                staging: {
+                    organization: "acme",
+                    project: "prod-bars",
+                    jwtAccessToken: jwt({
+                        aud: "https://dev-ohaafogw5p8uyx1m.us.auth0.com/api/v2/",
+                        exp: Math.floor(Date.now() / 1000) + 3600,
+                    }),
+                },
+            },
+            activeEnvironment: "production",
+        }));
+        fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+        fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({
+            deployment: "staging",
+            organization: "acme",
+            environment: "analytics",
+        }));
+        // No --yes and no terminal: it stops at the question, before any request.
+        const run = cred(["rm", "connection", "bq_demo"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(2);
+        (0, chai_1.expect)(run.stderr).to.contain("Using acme/analytics on staging, pinned in .credible/config.json.");
+        (0, chai_1.expect)(run.stderr).to.contain("(acme/analytics on staging)");
+        (0, chai_1.expect)(run.stderr).to.not.contain("global-org");
+    });
+    // The pin keeps naming its own deployment, so a login to another one would
+    // store tokens nothing in this directory reads.
+    it("refuses a login to another deployment inside a pinned directory", () => {
+        fs_1.default.mkdirSync(path_1.default.join(workDir, ".credible"));
+        fs_1.default.writeFileSync(path_1.default.join(workDir, ".credible", "config.json"), JSON.stringify({
+            deployment: "staging",
+            organization: "acme",
+            environment: "prod-bars",
+        }));
+        const before = fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8");
+        const run = cred(["login", "videoamp", "-c", "aws", "--no-browser"]);
+        (0, chai_1.expect)(run.status, run.stderr).to.equal(1);
+        (0, chai_1.expect)(run.stderr).to.contain("This directory is pinned to the staging deployment, so a login to videoamp here would not be used by anything in it.");
+        (0, chai_1.expect)(run.stderr).to.contain(`set "deployment": "videoamp" in ${fs_1.default.realpathSync(workDir)}/.credible/config.json`);
+        (0, chai_1.expect)(fs_1.default.readFileSync(path_1.default.join(home, ".cred"), "utf-8")).to.equal(before);
+    });
+    // Every command against a resource is `cred <verb> <resource>`. The old
+    // top-level verbs stay, listed, so nothing that uses them breaks.
+    describe("command shapes", () => {
+        it("names itself cred in help, not the file it runs from", () => {
+            (0, chai_1.expect)(cred(["--help"]).stdout).to.match(/^Usage: cred /);
+        });
+        // An agent learns a command from --help alone: the README does not ship
+        // with the CLI.
+        it("documents what publish uploads and prints, in publish --help and add version --help", () => {
+            for (const command of [["publish"], ["add", "version"]]) {
+                const help = cred([...command, "--help"]).stdout;
+                (0, chai_1.expect)(help, command.join(" ")).to.contain(".credignore");
+                // Rendered from PUBLISH_EXCLUDES, so a credential file is named.
+                (0, chai_1.expect)(help, command.join(" ")).to.contain("publisher.config.json, .env");
+                (0, chai_1.expect)(help, command.join(" ")).to.contain('latest ("now", "when-built" or "no")');
+            }
+        });
+        // An agent that ran a plain `cred init` sat on a foreground publisher,
+        // with no `malloy` tools until it was restarted.
+        it("tells an agent, before it runs init, that init needs a session restart", () => {
+            const help = cred(["init", "--help"]).stdout;
+            (0, chai_1.expect)(help).to.contain("cred init --no-start");
+            (0, chai_1.expect)(help).to.contain("Ask the user to restart you");
+            (0, chai_1.expect)(cred(["--help"]).stdout).to.contain("read `cred init --help`");
+        });
+        it("accepts list for ls", () => {
+            const run = cred(["list", "environments", "--help"]);
+            (0, chai_1.expect)(run.status, run.stderr).to.equal(0);
+            (0, chai_1.expect)(run.stdout).to.contain("List all environments.");
+        });
+        it("offers add version / add run / update version / update run, and keeps the old verbs listed", () => {
+            const top = cred(["--help"]).stdout;
+            for (const old of [
+                "publish",
+                "archive",
+                "unarchive",
+                "rerun",
+                "cancel-run",
+            ]) {
+                (0, chai_1.expect)(top).to.match(new RegExp(`^  ${old}\\b`, "m"));
+            }
+            (0, chai_1.expect)(cred(["add", "--help"]).stdout).to.match(/version[\s\S]*run/);
+            (0, chai_1.expect)(cred(["update", "--help"]).stdout).to.match(/version[\s\S]*run/);
+        });
+        it("refuses an update that changes nothing, naming the flag", () => {
+            const version = cred(["update", "version", "orders", "1.0.0"]);
+            (0, chai_1.expect)(version.status).to.equal(1);
+            (0, chai_1.expect)(version.stderr).to.contain("Pass --archived");
+            const run = cred(["update", "run", "orders", "run-1"]);
+            (0, chai_1.expect)(run.status).to.equal(1);
+            (0, chai_1.expect)(run.stderr).to.contain("Pass --cancel");
+        });
+    });
+});
+//# sourceMappingURL=agent-contract.spec.js.map