@tokenoftrust/cli 2.4.7 → 2.4.9

package/README.md

@@ -73,4 +73,4 @@ A clean short name (`staff`, `dev`, `test-7`) becomes a readable `credentials.<n
 
 ## Design notes
 
-Dependency-free by design (global `fetch` + `git` + the system `tar`), so `npm i -g @tokenoftrust/cli` stays light. `tot dev` is the only command that pulls in the storefront runner: for a standalone checkout it downloads the moat-free runner artifact (`dev_renderer_artifact`, entitlement-gated) once per version to `~/.tot/cache/renderer/<version>/`, `pnpm install`s it there (via corepack — no separate pnpm install needed), and reuses that cache on every later run. See `src/` for the small modules: `context.mjs` (detection), `mcp.mjs` (transport), `auth.mjs` (the identity seam), `commands/`.
+Dependency-free by design (global `fetch` + `git` + the system `tar`), so `npm i -g @tokenoftrust/cli` stays light. `tot dev` is the only command that pulls in the storefront runner: for a standalone checkout it downloads the moat-free runner once per version — from the public npm package `@tokenoftrust/storefront-runner`, after the entitlement-gated `dev_renderer_artifact` answers `use_npm` (its artifact store is not kept in step with npm) — to `~/.tot/cache/renderer/`, `pnpm install`s it there (via corepack — no separate pnpm install needed), and reuses that cache on every later run. See `src/` for the small modules: `context.mjs` (detection), `mcp.mjs` (transport), `auth.mjs` (the identity seam), `commands/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.7",
+  "version": "2.4.9",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/admission-hint.mjs

@@ -0,0 +1,36 @@
+/**
+ * The next step to print when the storefront refuses a call with 401/403.
+ *
+ * The server's admission rule (apps/storefront lib/pipeline/admission.ts) names exactly what is
+ * missing in `admission.missing[].grant`, and its reason is already in the refusal's `error`.
+ * The hint follows that answer instead of restating a policy of its own: a client copy of the
+ * rule goes stale — every refusal here used to say "you need a live ship-on-behalf grant", which
+ * is wrong for an unpaid store, where an invited developer needs no grant at all.
+ */
+
+/** The grant names a refusal body reports missing, or `[]` when it names none. */
+export function missingGrantsOf(body) {
+  const missing = body && typeof body === "object" ? body.admission?.missing : undefined;
+  return Array.isArray(missing)
+    ? missing.map((m) => m?.grant).filter((g) => typeof g === "string")
+    : [];
+}
+
+/** One actionable next step for a refused call, from the grants the server named. */
+export function refusalHint(status, missingGrants = []) {
+  if (status === 401 || missingGrants.includes("session")) return "run `tot login`, then re-run";
+  if (missingGrants.includes("tenant-binding")) {
+    return "your sign-in is for a different store — check --tenant, then re-run";
+  }
+  if (missingGrants.includes("tenant-standing")) {
+    return "ask the store owner to invite you to this store from its Team page, then re-run";
+  }
+  if (missingGrants.includes("ship-on-behalf")) {
+    return "this store's live site is active, so ask the store owner for a ship-on-behalf grant from its Team page, then re-run";
+  }
+  if (missingGrants.includes("owner-standing")) return "only the store owner can do this";
+  if (missingGrants.includes("console-capability")) {
+    return "the operator secret is acting with preview-access — set X-Tot-Capability: ship-on-behalf (or ACCEPT_OPERATOR_CAPABILITY), then re-run";
+  }
+  return "ask the store owner for access to this store — or use an operator secret authorised for it";
+}

package/src/commands/accept.mjs

@@ -47,8 +47,9 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { scopeToTenant } from "../tenant-scope.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
-// login and integrate as themselves (server gates on their live ship-on-behalf grant).
+// login and integrate as themselves (the server's admission rule decides).
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 // The doctor PUSH: on a failed accept/integrate, auto-append the COMPACT
 // "here's what's blocking you" summary over the SAME transport we just used, so a
 // developer doesn't have to remember to run `tot preview doctor` themselves.
@@ -529,7 +530,7 @@ export async function runIntegrate(
   //    - OPERATOR SECRET (operators/CI): Bearer + X-Tot-Owner on the generic host.
   //    - VIEWER SESSION (an invited developer, no secret): mint a `tot_session` from
   //      their OWN `tot` login on the TENANT'S host and send it as a cookie. The
-  //      server authorizes on their live ship-on-behalf grant either way.
+  //      server's admission rule authorizes either way.
   //    No `content-type` here: it's added per-POST; the mergeable preflight GET wants none.
   let authHeaders;
   if (secret) {
@@ -688,7 +689,7 @@ function reportIntegrateHttpError(result, res, { tenant, label }) {
     fail(
       `the integration queue refused the request: ${msg}`,
       res.status === 401 || res.status === 403
-        ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
+        ? refusalHint(res.status, missingGrantsOf(result.raw))
         : res.status === 404
           ? `check that ${label} has a built candidate in ${tenant}'s queue (\`tot pr list --tenant ${tenant}\`)`
           : "check --tenant / --url / --pr, then re-run",

package/src/commands/dev.mjs

@@ -185,7 +185,8 @@ async function runStandalone(workspace, args, ctx) {
       // Entitled artifact unavailable — stay NATIVE on the public npm runner
       // (@tokenoftrust/storefront-runner, the SAME renderer bits), so
       try {
-        console.error(`~ couldn't set up your store preview the usual way (${e.message}) — using the public preview engine instead.`);
+        const notice = artifactFallbackNotice(e);
+        if (notice) console.error(notice);
         return await runNativePublic(workspace, args, ctx);
       } catch (e2) {
         console.error(formatError(e2));
@@ -284,7 +285,31 @@ function runMonorepo(ctx, argv) {
  * specifically and falls back to Docker instead of hard-failing. Exported so
  * `tot start` can catch it too and fall back the same way.
  */
-export class NativeArtifactUnavailableError extends Error {}
+export class NativeArtifactUnavailableError extends Error {
+  /** @param {string} message @param {{ expected?: boolean }} [opts] */
+  constructor(message, { expected = false } = {}) {
+    super(message);
+    // True when the MCP answered that npm is the renderer source: the normal
+    // fallback, not a fault, so it is not reported to the developer.
+    this.expected = expected;
+  }
+}
+
+// dev_renderer_artifact statuses meaning "the artifact store holds no current
+// runner — install it from npm". `use_npm` is the current non-error answer;
+// `stale_artifact` / `not_found` are the error-shaped answers older servers send.
+const USE_NPM_STATUSES = new Set(["use_npm", "stale_artifact", "not_found"]);
+
+/**
+ * The line `tot dev` prints when it falls back from the entitled artifact to the
+ * public npm runner, or null when the fallback is the expected path.
+ * @param {NativeArtifactUnavailableError} e
+ * @returns {string|null}
+ */
+export function artifactFallbackNotice(e) {
+  if (e.expected) return null;
+  return `~ couldn't set up your store preview the usual way (${e.message}) — using the public preview engine instead.`;
+}
 
 /**
  * The local landing URL, shared by the native and Docker paths. The store's path is its canonical
@@ -724,12 +749,18 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
       await establishSession(client, { env: process.env });
     }
     const res = await client.callTool("dev_renderer_artifact", {});
+    if (USE_NPM_STATUSES.has(res?.status)) {
+      throw new NativeArtifactUnavailableError(res.message || "the renderer is served from npm", { expected: true });
+    }
     if (!res?.url || !res?.version) {
       throw new Error(res?.error || "no renderer-artifact URL returned");
     }
     credential = res;
   } catch (e) {
-    throw new NativeArtifactUnavailableError(String(e?.message || e));
+    if (e instanceof NativeArtifactUnavailableError) throw e;
+    throw new NativeArtifactUnavailableError(String(e?.message || e), {
+      expected: USE_NPM_STATUSES.has(e?.diagnostic?.serverStatus),
+    });
   }
 
   try {

package/src/commands/preview-doctor.mjs

@@ -38,6 +38,7 @@
  */
 import { fail } from "../errors.mjs";
 import { resolveOperatorSecret } from "./ship.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 import { resolveViewerTransport } from "../viewer-session.mjs";
 import {
   DOCTOR_PATH,
@@ -165,7 +166,7 @@ export async function runDoctor(
     console.error(
       fail(
         `not authorized to diagnose ${tenant}'s merges: ${data?.error || `HTTP ${res.status}`}`,
-        "you need a live ship-on-behalf grant on this tenant (ask the store owner), or an operator secret authorised for it — then re-run",
+        refusalHint(res.status, missingGrantsOf(data)),
       ),
     );
     return 2;

package/src/commands/revert.mjs

@@ -45,8 +45,9 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 // speak ONE operator-auth contract.
 import { resolveOperatorSecret } from "./ship.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
-// login. The server still gates the request on their live ship-on-behalf grant.
+// login. The server's admission rule still gates the request.
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
@@ -337,7 +338,7 @@ export async function runRevert(
       fail(
         `the revert request was refused: ${msg}`,
         res.status === 401 || res.status === 403
-          ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
+          ? refusalHint(res.status, missingGrantsOf(data))
           : "check --tenant / --url / --preview, then re-run",
       ),
     );

package/src/commands/ship.mjs

@@ -47,7 +47,8 @@
  *
  * TRANSPORT: operators/CI may use a Bearer operator secret. A signed-in owner or
  * developer instead mints a storefront viewer session from their OWN `tot login`
- * identity; the server still enforces the live owner / `ship-on-behalf` grant.
+ * identity; the server's admission rule decides who may ship (owner; a live
+ * `ship-on-behalf` grant; or, while the store is unpaid, any developer invited to it).
  */
 import { createHash } from "node:crypto";
 import { fail } from "../errors.mjs";
@@ -76,10 +77,10 @@ const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live
                             record the required reason, then continue publishing
   tot ship --no-open         don't open the live URL in your browser
 
-  Authentication: a signed-in owner/developer with a live ship-on-behalf grant
-  can use their own \`tot login\` session. Operators/CI may instead provide a
-  secret via PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET,
-  TOT_OPERATOR_SECRET, or --secret.
+  Authentication: use your own \`tot login\` session if you own the store, hold
+  a live ship-on-behalf grant, or — while the store is unpaid — were invited to
+  it as a developer. Operators/CI may instead provide a secret via
+  PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET, or --secret.
 
   \`tot ship\` has ONE meaning: it publishes the tenant's shared preview
   aggregate — the batch of PRs that integrated cleanly and went GREEN — to

package/src/viewer-session.mjs

@@ -6,9 +6,10 @@
  * a storefront VIEWER session from the developer's OWN MCP token (POST
  * /api/dev/cli-session on the tenant's own host, which resolves WHO the opaque token
  * is via the MCP and hands back a `tot_session` cookie), then hands the caller a
- * cookie-based transport pointed at the tenant host. Authorization is still the
- * developer's live `ship-on-behalf` grant, enforced server-side at the ship route —
- * this only carries their identity, it grants nothing.
+ * cookie-based transport pointed at the tenant host. Authorization is the server's
+ * admission rule at the ship route (owner; a live `ship-on-behalf` grant; or, while the
+ * store is unpaid, any developer invited to it) — this only carries their identity, it
+ * grants nothing.
  *
  * Minted FRESH per call (no disk cache): a `tot accept` is interactive + infrequent,
  * and minting-per-call means a revoked session/grant is never honored past its life.