@catalyst-cloud/cli 0.13.0 → 0.14.0

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -1,51 +1,34 @@
 # What the browser owns
 
-Some steps you cannot do, and the honest thing is to say which and why. There are two kinds, and they deserve different sentences.
+## Browser by construction
 
-## Kind one: browser by construction
+Each is an authorization a person grants in their own session, so no command will ever do it. Say **by construction**; a person told "not supported yet" waits for a feature that will never come.
 
-These will never be a command, on any release. Each is an authorization a person grants in their own session; a credential that could perform one would defeat the point of it.
+| step | where |
+| -- | -- |
+| approving the login | the URL and short code `catalyst login` printed |
+| enrolling a coding account, or replacing its credential | the AI accounts page the script printed |
+| connecting the Linear integration, installing the GitHub App | `<their cloud>/settings/connections` (Settings → Integrations) |
+| creating `<your GitHub org>/thoughts` and letting the App reach it | GitHub, then the App's installation page for that org: All repositories, or add `thoughts` (step 5 of `references/the-one-path.md`) |
+| connecting personal Linear, then personal GitHub | the URL `catalyst connections personal <linear\|github> start` printed |
 
-| step | where | what you say |
-| -- | -- | -- |
-| approving the login | the URL and short code that `catalyst login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
-| enrolling a coding account, or replacing its credential | the AI accounts page the script printed for the `coding accounts` part | "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it. Tell me when it is saved and I will read it back." |
-| connecting the Linear integration | `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today) | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
-| installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked and `<your GitHub org>/thoughts`." |
-| creating or confirming `<your GitHub org>/thoughts`, and letting the GitHub App reach it | GitHub, then the GitHub App's installation page for that org | "Catalyst's cloud phases write their notes to `<your GitHub org>/thoughts`, in the org that owns the code repository. Check it exists. If not, create a private repository named `thoughts`, initialized with a README. Then, on the GitHub App's installation page for that org, choose All repositories, or add `thoughts` to the selected repositories." |
-| connecting personal Linear | the URL printed by `catalyst connections personal linear start` | "Approve your own Linear account in this browser. I will check the grant status afterward." |
-| connecting personal GitHub, after the tenant GitHub App is installed and its repository is registered | the URL printed by `catalyst connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
+## Not a command yet
 
-Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
+Their routes take a browser session, not a key. Call them gaps, route the person through the browser, and never guess at a route.
 
-## Kind two: not a command yet
+| step | where |
+| -- | -- |
+| registering a repository and attaching it to a project | `<their cloud>/settings/projects` (Settings → Your projects) |
+| approving one repository's declaration, and entering its values | that repository's Environment page (`references/declaring-a-repository.md`) |
 
-These are settings pages today because the routes behind them take a browser session and not a key. A key-callable path is being built. They are gaps, and you should say so in those words — but you must still route the person through the browser, and you must not guess at a route. Trying one and being refused wastes their time and teaches them the tool is unreliable.
+`catalyst environment` handles a workspace-wide declaration. ⛔ Only the CLI makes requests; if you find yourself building a URL for one of these, stop.
 
-| step | where | what you say |
-| -- | -- | -- |
-| registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
-| approving the environment **for one repository**, and entering its values | that repository's Environment page under `<their cloud>/settings/repositories`: the Setup declaration tab's Approve this revision button approves, and the Environment variables and Secrets tabs take the values | "The names come from `.catalyst/catalyst.toml` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst environment` does those.) |
+## The link to hand over
 
-⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
-
-## The URL to hand over
-
-Never type a host from memory. `catalyst status` prints the API it is connected to on its `API:` line, and `node scripts/where-am-i.mjs` prints ready-made links built from it. Use those. A person pointed at the wrong tenant's settings page has a worse afternoon than one pointed at no page at all.
+Use the links `node scripts/where-am-i.mjs` prints, built from the `API:` line of `catalyst status`, never a host from memory: the wrong account's settings page costs more than none.
 
 ## Handing over, and coming back
 
-The shape is always the same three parts, and all three matter:
-
-1. **What to open.** One link, and what they will see on it.
-2. **What to do there.** One action, named the way the page names it.
-3. **What you need back.** Not "let me know when you are done" — say what you will check and how. "When you have saved it, say so and I will re-read your tenant and tell you what it now says."
-
-Then **wait**. Do not run anything while they are mid-flow, do not narrate, and do not move to the next step.
-
-When they come back:
+Hand over one link, one action named the way the page names it, and what you will check when they are back. Then wait, without running anything.
 
-- Re-run `node scripts/where-am-i.mjs` and read them the part that should have changed.
-- If it changed, say what it now says and move on.
-- If it did not, refresh the contract once (`catalyst contract --refresh`) and read it again — the contract is cached, and a page can be ahead of it by a few seconds.
-- If it still did not, report both: what the page told them, and what the instrument says. Ask what they saw. **Never mark a step done because the person said a page worked** — the instrument is the record, and this is exactly where a confident false "all set" costs them an hour later.
+When they come back, read the part again (step 5 of a turn in `SKILL.md`). The contract is cached, so a page can be seconds ahead of it: refresh once before reporting a disagreement, then ask what they saw. A step is done when the instrument reads done.

package/skills/{catalyst-setup → catalyst-onboard}/scripts/check.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // check.mjs — "am I set up?" in one verdict: the machine checks the CLI runs (Node, the connection,
 // the cached contract, the CLI path, the skills, the SDK, the optional replica) plus every team's
-// readiness vector from the tenant contract, then the list of who can click what. Wraps
-// `catalyst-skills ready --json`; reports, never repairs. Exit 0 READY, 1 NOT READY, 2 not connected.
-import { parseJson, runCli } from "./lib/cli.mjs";
+// readiness from the account's contract, then the list of who can click what. Wraps
+// `catalyst ready --json`; reports, never repairs. Exit 0 READY, 1 NOT READY, 2 not connected.
+import { runCli, tryJson } from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/check.mjs [--json]
 
@@ -12,7 +12,8 @@ verdict, and a "who can click what" list grouped by the person or role each fix
 A note never flips the verdict (the replica is optional; an informational readiness check is a note).
 
 --json prints the CLI's report document {ready, checks[]} unchanged.
-Exit 0 READY, 1 NOT READY, 2 this machine is not connected to a tenant yet.`;
+Exit 0 READY, 1 NOT READY, 2 this machine is not connected yet or the CLI could not run.
+How to read each line: references/reading-ready.md.`;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
@@ -27,13 +28,13 @@ if (unknown.length > 0) {
 }
 
 const res = runCli(["ready", "--json"]);
-if (res.code === 2) {
-  console.error(res.stderr.trim() || "catalyst-skills ready refused");
+const report = tryJson(res.stdout);
+if (!res.ran || (res.code === 2 && !report)) {
+  console.error(res.stderr.trim() || "catalyst ready refused");
   process.exit(2);
 }
-const report = parseJson(res.stdout);
 if (!report || !Array.isArray(report.checks)) {
-  console.error(res.stderr.trim() || res.stdout.trim() || "catalyst-skills ready printed no report");
+  console.error(res.stderr.trim() || res.stdout.trim() || "catalyst ready printed no report");
   process.exit(res.code === 0 ? 1 : res.code);
 }
 if (args.includes("--json")) {
@@ -70,6 +71,6 @@ if (failures.length > 0) {
 const notes = report.checks.filter((c) => c.note && !c.ok);
 if (notes.length > 0) {
   console.log("");
-  console.log(`Notes that do not block: ${notes.map((c) => c.id).join(", ")} — see references/what-each-check-means.md`);
+  console.log(`Notes that do not block: ${notes.map((c) => c.id).join(", ")} — see references/reading-ready.md`);
 }
 process.exit(report.ready ? 0 : 1);

package/skills/catalyst-onboard/scripts/lib/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst CLI.
 // The CLI holds the SDK and the key; this file holds neither. It reads customer.json only to learn
 // where the CLI lives. Run any script beside this one with --help; this file is a library.
 //
@@ -13,7 +13,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const NOT_CONFIGURED_EXIT = 2;
 export const CONNECT_LINE = CONNECT_COMMAND;
 
@@ -53,11 +55,11 @@ export function cliTarget(cfg = tryLoadConfig()) {
   const recorded = recordedPath !== null;
   return recorded
     ? { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}`, recorded: true }
-    : { command: "npx", prefix: [PACKAGE], via: `npx ${PACKAGE}`, recorded: false };
+    : { command: "npx", prefix: NPX_ARGS, via: `npx -p ${PACKAGE} catalyst`, recorded: false };
 }
 
 /**
- * Run one catalyst-skills verb. Returns {code, stdout, stderr, ran} and never exits: a verb that
+ * Run one catalyst verb. Returns {code, stdout, stderr, ran} and never exits: a verb that
  * refuses because the machine is not connected is a READING, not a failure of this script.
  * `ran` is false when the CLI could not be started at all.
  */

package/skills/catalyst-onboard/scripts/lib/credential.mjs

@@ -6,12 +6,12 @@
 //
 // customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
 // session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
-// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// catalyst CLI, which authenticates with whichever is present and refreshes a login's token
 // itself. A new credential kind lands here, once.
 
 /** The command that connects this machine, as every not-connected line names it. */
 export const CONNECT_COMMAND =
-  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+  "npx -p @catalyst-cloud/cli catalyst login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx -p @catalyst-cloud/cli catalyst login)";
 
 /** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
 export function hasCredential(cfg) {

package/skills/catalyst-onboard/scripts/lib/project-coverage.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Shared coverage formatter used by where-am-i; --help documents its input contract.
+if (process.argv.includes("--help")) {
+  process.stdout.write(
+    "Usage: imported by where-am-i; compares project rows with saved team stage mappings.\n",
+  );
+  process.exit(0);
+}
+
+/** Compare the full Catalyst project inventory with teams that actually have saved stage rows. */
+export function projectCoverage(projects, teams) {
+  const mappedTeamIds = new Set(
+    teams
+      .filter(
+        (team) =>
+          team &&
+          (team.id ?? team.teamId) &&
+          team.stages &&
+          Object.keys(team.stages).length > 0,
+      )
+      .map((team) => team.id ?? team.teamId),
+  );
+  const mapped = [];
+  const unmapped = [];
+  for (const project of projects) {
+    (mappedTeamIds.has(project.linearTeamId) ? mapped : unmapped).push(project);
+  }
+  return { mapped, unmapped, total: projects.length };
+}
+
+export function projectCoverageLines(projects, teams) {
+  const coverage = projectCoverage(projects, teams);
+  const teamById = new Map(teams.map((team) => [team.id ?? team.teamId, team]));
+  const lines = [
+    `${coverage.mapped.length} of your ${coverage.total} projects have their Linear team mapped.`,
+  ];
+  for (const project of coverage.mapped) {
+    const team = teamById.get(project.linearTeamId);
+    const readiness = team?.readiness ?? {};
+    const bad = Array.isArray(readiness.checks)
+      ? readiness.checks.filter((check) => check.state !== "pass")
+      : [];
+    lines.push(
+      `${project.name} (${project.linearTeamKey ?? team?.teamKey ?? project.linearTeamId}): ${readiness.status ?? "unchecked"}${bad.length ? ` — ${bad.map((check) => `${check.id} ${check.state}`).join(", ")}` : ""}`,
+    );
+  }
+  if (coverage.unmapped.length > 0) {
+    lines.push(
+      `These ${coverage.unmapped.length} do not: ${coverage.unmapped.map((project) => project.name).join(", ")}`,
+    );
+  }
+  return { ...coverage, lines };
+}