@tokenoftrust/cli 2.0.28 → 2.1.1

package/bin/tot.mjs

@@ -56,6 +56,8 @@ const COMMANDS = [
   { invocation: "grants", blurb: "capability/tier/expiry per store you can act on" },
   { invocation: "clone [<tenant>]", blurb: "clone a store you can build on" },
   { invocation: "validate", blurb: "lint your store before you submit" },
+  { invocation: "capabilities", blurb: "what the platform supports, refuses, and has not built yet" },
+  { invocation: "report go-live --pages <dir>", blurb: "your store's go-live readiness report, from its page-check results" },
   { invocation: "dev", blurb: "run your store locally with save→reload" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
   { invocation: "ship", blurb: "publish the tenant's current green aggregate live (plan → confirm → ship)" },
@@ -175,6 +177,16 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "capabilities") {
+    const { run } = await import("../src/commands/capabilities.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "report") {
+    const { run } = await import("../src/commands/report.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "dev") {
     const { run } = await import("../src/commands/dev.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.28",
+  "version": "2.1.1",
   "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/capability-registry.mjs

@@ -0,0 +1,295 @@
+/**
+ * What the platform supports, what it refuses, and what it has not built yet.
+ *
+ * A migration constantly needs three answers, and until this file none were available without
+ * reading platform source:
+ *
+ *   1. Does the platform already do X, so I should wire it up rather than build it per-tenant?
+ *   2. If so, what populates it and what proves it?
+ *   3. If not — is that a GAP worth filing, or a REFUSAL I should stop asking for?
+ *
+ * THE THIRD TIER IS THE POINT. A registry that lists only what exists teaches nothing about the
+ * boundaries, so migrators keep requesting things that will never be granted — and the incautious
+ * hand-roll the refused thing locally, because nothing said no. `deliberately-refused` carries its
+ * reason for exactly that reason.
+ *
+ * NOT AUTHORITATIVE BY ASSERTION. Every entry names the file that implements it, and
+ * the CLI's capability-registry test proves those paths exist in the platform repository. They are
+ * the register's anti-drift proof, not part of what `tot capabilities` prints. A capability whose implementation is
+ * deleted or moved fails the suite rather than becoming a doc that lies — which is worse than no
+ * doc, because it is trusted.
+ */
+
+/**
+ * @typedef {object} Capability
+ * @property {string} id             stable slug; the argument to `tot capabilities --id`
+ * @property {string} label          how a human refers to it
+ * @property {tier} tier             what kind of support this is — see below
+ * @property {string} summary        one line, in a migrator's terms
+ * @property {string[]} implementedBy repo-relative paths that must exist (verified by test)
+ * @property {string} [populatedBy]  the migration step that fills it, when it carries data
+ * @property {string} [verifiedBy]   the gate that proves it, so a red gate can cite the capability
+ * @property {siteType[]} appliesTo  tenant shapes it is relevant to
+ * @property {string} [because]      REQUIRED for deliberately-refused: why, so nobody re-asks
+ * @property {string} [tracking]     REQUIRED for not-yet: the filed report, so it is not re-filed
+ *
+ * @typedef {'platform-core'|'app'|'plugin'|'deliberately-refused'|'not-yet'} tier
+ * @typedef {'commerce'|'marketing'} siteType
+ */
+
+/** @type {readonly Capability[]} */
+export const CAPABILITIES = [
+  // ---- platform-core: already built, wire it up rather than rebuilding per tenant ----
+  {
+    id: 'product-reviews',
+    label: 'Product reviews and ratings',
+    tier: 'platform-core',
+    summary:
+      'Per-product reviews and aggregate rating, harvested from the merchant\'s existing reviews '
+      + 'app during migration and emitted as JSON-LD. Aggregates come ONLY from sourced numbers — '
+      + 'scraped widget markup is refused and a half-populated aggregate is omitted entirely.',
+    implementedBy: [
+      'packages/public-runtime/src/product.ts',
+      'apps/storefront/src/lib/jsonld.ts',
+      'apps/storefront/src/lib/reviews.trust-proof.test.ts',
+    ],
+    populatedBy: 'catalog.2 (admin enrichment) — reviews.rating / reviews.rating_count metafields',
+    appliesTo: ['commerce'],
+  },
+  {
+    id: 'legacy-redirects',
+    label: 'Legacy URL redirects',
+    tier: 'platform-core',
+    summary:
+      'Declared old->new paths materialize into the PUBLISHED artifact and are served by the edge '
+      + 'function on the public path. They correctly 404 on the preview/test channel — that is by '
+      + 'design and is not a missing declaration.',
+    implementedBy: ['agency-kit/tools/validate-site.mjs'],
+    populatedBy: 'content/redirects.json in the tenant repo',
+    verifiedBy: 'Step 9 post-cutover crawl (not provable pre-cutover)',
+    appliesTo: ['commerce', 'marketing'],
+  },
+  {
+    id: 'theme-tokens',
+    label: 'Tenant theme tokens and style concept',
+    tier: 'platform-core',
+    summary:
+      'A tenant declares colour/type/shape tokens and a style concept; the platform supplies the '
+      + 'component CSS that consumes them. Conversion-role tokens (cta, trust, surface-card) name '
+      + 'the JOB a colour does so a tenant can move one without dragging the rest.',
+    implementedBy: [
+      'packages/public-runtime/src/tenant.ts',
+      'apps/storefront/src/styles/global.css',
+      'agency-kit/playbooks/style-concept.md',
+    ],
+    populatedBy: 'Step 4.5 (theme + style guide + style concept)',
+    verifiedBy: 'style-concept-audit ecommerceStyleGuide / guideCoverage',
+    appliesTo: ['commerce', 'marketing'],
+  },
+  {
+    id: 'compliance-notices',
+    label: 'Regulated-commerce compliance notices',
+    tier: 'platform-core',
+    summary:
+      'Age gate, PACT Act, Prop 65, adult-signature, excise-tax and shipping-restriction notices '
+      + 'as declared components with real legal meaning — not free text.',
+    implementedBy: ['apps/storefront/src/components/compliance'],
+    verifiedBy: 'preview_status compliance checks (age_gate, excise, jurisdiction)',
+    appliesTo: ['commerce'],
+  },
+  {
+    id: 'source-parity-baseline',
+    label: 'Source Lighthouse baseline',
+    tier: 'platform-core',
+    summary:
+      'The merchant\'s own pre-migration scores, captured before cutover, so parity can be judged '
+      + 'and improvement proven. NOT re-derivable once the hostname moves.',
+    implementedBy: [
+      'agency-kit/tools/capture-source-baseline.mjs',
+      'docs/devkit-staging/tools/lib/lighthouse-parity.mjs',
+    ],
+    populatedBy: 'Step 8 — capture-source-baseline.mjs, before cutover',
+    verifiedBy: 'perf gate parity verdicts (regression / parity / giveaway)',
+    appliesTo: ['commerce', 'marketing'],
+  },
+
+  // ---- app: a reviewed integration the merchant selects ----
+  {
+    id: 'analytics-adapter',
+    label: 'Analytics via reviewed adapter',
+    tier: 'app',
+    summary:
+      'A tenant selects a REVIEWED adapter and supplies a public destination id. Ids are per '
+      + 'stage — a non-live stage reusing the live id resolves the whole integration to nothing.',
+    implementedBy: ['docs/architecture/analytics-activation.md'],
+    populatedBy: 'analytics.json in the tenant repo (add-on stage: analytics)',
+    appliesTo: ['commerce', 'marketing'],
+  },
+
+  // ---- deliberately-refused: stop asking, and do NOT hand-roll it locally ----
+  {
+    id: 'tag-container',
+    label: 'Tag manager / container snippet',
+    tier: 'deliberately-refused',
+    summary: 'Pasting a GTM-style container id or executable tag markup.',
+    because:
+      'A tenant never supplies executable markup, selectors, secrets, wildcard origins or a '
+      + 'container id. Refusing all of them is what makes measurement possible on a REGULATED '
+      + 'storefront at all. "Add this tracking snippet" is never "where do I paste it" — it is '
+      + '"which reviewed adapter covers this destination", and if none does that is a reviewed '
+      + 'platform change, not tenant content. Regulated tenants CAN run reviewed adapters, GA4 '
+      + 'included; only uncertified elevated-parent code is refused.',
+    implementedBy: ['docs/architecture/analytics-activation.md'],
+    appliesTo: ['commerce', 'marketing'],
+  },
+  {
+    id: 'fabricated-trust-claims',
+    label: 'Ratings, testimonials, badges or guarantees without evidence',
+    tier: 'deliberately-refused',
+    summary: 'Filling a trust component with a plausible number or quote to clear a gate.',
+    because:
+      'The theme claimsPolicy requires merchant-provided evidence and human approval for product '
+      + 'claims, customer counts, ratings, testimonials, badges, guarantees and any health or '
+      + 'cessation claim. On a regulated storefront a fabricated rating or badge is a compliance '
+      + 'exposure, not a shortcut. The quality bar REFUSES approval while such components ship as '
+      + 'placeholders, which is the enforcement, not merely the advice.',
+    implementedBy: ['docs/devkit-staging/tools/style-concept-audit.mjs'],
+    verifiedBy: 'style-concept-audit ecommerceStyleGuide.unsourcedComponents',
+    appliesTo: ['commerce'],
+  },
+  {
+    id: 'origin-compute-public-path',
+    label: 'Origin compute in front of public pages',
+    tier: 'deliberately-refused',
+    summary: 'Putting the Worker in the public request path to compose a response per request.',
+    because:
+      'Public pages are CDN -> content-addressed storage with at most ONE submillisecond edge '
+      + 'function. Google ranks on field Core Web Vitals from real visits, so origin latency on a '
+      + 'cache miss is a direct commercial cost and every layer is another term in the uptime '
+      + 'product. Nearly every such request is an undecided variant set: ask what N is. Bounded N '
+      + 'is a cache-key dimension; per-user N is a static shell plus an authenticated hydrate. A '
+      + 'genuine exception amends ADR 0013 rather than becoming a silent local decision.',
+    implementedBy: ['docs/architecture/decisions/0013-public-serving-contract.md'],
+    appliesTo: ['commerce', 'marketing'],
+  },
+  {
+    id: 'tenant-data-in-platform-repo',
+    label: 'Committing a merchant\'s content or catalog to the platform repo',
+    tier: 'deliberately-refused',
+    summary: 'Storing tenant pages, catalog or analytics config in this monorepo.',
+    because:
+      'A tenant\'s content belongs in its own Gitea repo — the split is what makes extraction a '
+      + 'subtree operation rather than a rescue. Three routes reach this repo and all three are '
+      + 'guarded and fail closed; the third has no gitignore friction at all, so a plain `git add` '
+      + 'silently succeeds. Existing entries are recorded exceptions with reasons, never a pattern '
+      + 'to copy.',
+    implementedBy: ['scripts/tenant/check-no-tracked-real-tenants.mjs'],
+    verifiedBy: 'pnpm run check (tenant-data guard)',
+    appliesTo: ['commerce', 'marketing'],
+  },
+
+  // ---- not-yet: a real gap, already filed; do not re-file ----
+  {
+    id: 'agent-readiness',
+    label: 'Agent readiness (WebMCP tools, agent accessibility tree)',
+    tier: 'not-yet',
+    summary:
+      'Whether an AI agent can actually shop the store — Lighthouse 13 scores this as its fifth '
+      + 'category, agentic-browsing: agent accessibility tree, WebMCP registered tools, WebMCP '
+      + 'schema validity, form coverage, CLS, llms.txt. We ship llms.txt (measured live and reported '
+      + 'as advisory preview evidence); the '
+      + 'WebMCP half has no implementation anywhere in the runtime. Validation measures the '
+      + 'category, so the score is visible and the dimension is offerable as an add-on — but a '
+      + 'good score needs the surface built.',
+    implementedBy: [
+      'agency-kit/tools/capture-source-baseline.mjs',
+      'docs/devkit-staging/tools/validate-page-browser.mjs',
+      'apps/storefront/src/lib/diag/evidence.ts',
+    ],
+    populatedBy: 'Lighthouse agentic-browsing category, captured per page at Step 8',
+    verifiedBy: 'tot report go-live (the agent-readiness row)',
+    tracking: 'fb-1790020895985-emlrk6',
+    appliesTo: ['commerce'],
+  },
+  {
+    id: 'commerce-sync-detection',
+    label: 'Automatic order-sync / product-sync status',
+    tier: 'not-yet',
+    summary:
+      'Whether a tenant\'s order sync and product sync are actually wired and exercised. These are '
+      + 'builder-facing jobs on the PUBLIC TOT MCP, run against the merchant\'s existing store, so '
+      + 'Step 8 cannot see them: it validates the storefront, not the integrations behind it. '
+      + 'Until a status read exists, the go-live report carries them as recorded confirmations '
+      + 'with explicit provenance, and an absent record reads as NOT CONFIRMED — never as passing.',
+    implementedBy: ['packages/cli/src/go-live-report.mjs'],
+    populatedBy: 'commerceSync in the store checkout\'s .tot/migration-state.json (hand-recorded today)',
+    tracking: 'fb-1790015097742-qk3m8w',
+    appliesTo: ['commerce'],
+  },
+  {
+    id: 'site-social-proof',
+    label: 'Site-level social proof (aggregate rating, testimonials)',
+    tier: 'not-yet',
+    summary:
+      'A store-wide rating and an attributable testimonial type. Per-PRODUCT reviews are '
+      + 'platform-core and well built; there is no equivalent for the whole store, so the style '
+      + 'guide ships a placeholder the platform gives no honest way to fill. A real aggregate is '
+      + 'derivable from catalog data already harvested.',
+    implementedBy: ['apps/storefront/src/components/commerce/ReviewSummary.astro'],
+    tracking: 'fb-1790007573300-xs1zcc',
+    appliesTo: ['commerce'],
+  },
+];
+
+/** Tiers whose support is real today — the ones a migration can wire up. */
+export const SUPPORTED_TIERS = ['platform-core', 'app', 'plugin'];
+
+/** @param {string} id */
+export function capability(id) {
+  return CAPABILITIES.find((c) => c.id === id) ?? null;
+}
+
+/**
+ * Capabilities relevant to a tenant shape. A commerce tenant should never be told about a
+ * marketing-only capability, and vice versa — that noise is what makes a catalogue unread.
+ * @param {string} [siteType]
+ */
+export function capabilitiesFor(siteType) {
+  if (!siteType) return CAPABILITIES;
+  return CAPABILITIES.filter((c) => c.appliesTo.includes(/** @type {any} */ (siteType)));
+}
+
+/** Is this supported today, refused on purpose, or simply absent? */
+export function supportStatus(id) {
+  const found = capability(id);
+  if (!found) return { known: false, supported: false, refused: false, gap: false };
+  return {
+    known: true,
+    supported: SUPPORTED_TIERS.includes(found.tier),
+    refused: found.tier === 'deliberately-refused',
+    gap: found.tier === 'not-yet',
+    capability: found,
+  };
+}
+
+/**
+ * The answer a migrator actually wants, in one string: what to DO about this capability.
+ * Keeping it here rather than in the CLI means a gate, a report or a tool can all cite the same
+ * sentence instead of each inventing its own phrasing.
+ */
+export function describeCapability(id) {
+  const s = supportStatus(id);
+  if (!s.known) return `Unknown capability "${id}". Run \`tot capabilities\` to see the register.`;
+  const c = /** @type {Capability} */ (s.capability);
+  if (s.refused) {
+    return `${c.label} — REFUSED ON PURPOSE. ${c.because} Do not build a local workaround; if the `
+      + 'need is real it is a reviewed platform change.';
+  }
+  if (s.gap) {
+    return `${c.label} — NOT BUILT YET, already filed as ${c.tracking}. Do not re-file; add `
+      + 'evidence to that report instead.';
+  }
+  return `${c.label} — SUPPORTED (${c.tier}). ${c.summary}`
+    + (c.populatedBy ? ` Populated by: ${c.populatedBy}.` : '')
+    + (c.verifiedBy ? ` Verified by: ${c.verifiedBy}.` : '');
+}

package/src/commands/capabilities.mjs

@@ -0,0 +1,120 @@
+/**
+ * `tot capabilities` — ask the platform what it supports before building something per store.
+ *
+ *   tot capabilities [--site-type commerce|marketing]   the whole register
+ *   tot capabilities --id <capability-id>                what fills it, what proves it, what to do
+ *   tot capabilities --gaps                              filed gaps: add evidence, do not re-file
+ *   tot capabilities --refused                           refused on purpose: do not work around
+ *   tot capabilities --json                              machine-readable
+ *
+ * The register ships inside this CLI release, so the answer tracks the platform version the CLI
+ * was released with. Exit 0 on an answer; 2 on a usage error; 4 for an unknown id, so a typo never
+ * reads as "no such capability, go build it".
+ */
+import { CAPABILITIES, capabilitiesFor, describeCapability, supportStatus } from "../capability-registry.mjs";
+
+const TIER_MARK = {
+  "platform-core": "BUILT   ",
+  app: "APP     ",
+  plugin: "PLUGIN  ",
+  "deliberately-refused": "REFUSED ",
+  "not-yet": "GAP     ",
+};
+
+const SITE_TYPES = ["commerce", "marketing"];
+
+export const USAGE = `tot capabilities — what the platform supports, refuses, and has not built yet
+
+  tot capabilities [--site-type commerce|marketing]  list the register
+  tot capabilities --id <id>                         what fills it, what proves it, what to do
+  tot capabilities --gaps                            filed gaps (add evidence, do not re-file)
+  tot capabilities --refused                         refused on purpose (do not work around)
+  tot capabilities --json                            machine-readable output`;
+
+/**
+ * A capability as the public CLI prints it. `implementedBy` names platform-repository files: it is
+ * the register's anti-drift proof, checked by the platform's own tests, and means nothing to a
+ * developer outside that repository.
+ * @param {import("../capability-registry.mjs").Capability} c
+ */
+export function publicCapability(c) {
+  const { implementedBy: _internal, ...rest } = c;
+  return rest;
+}
+
+/** @param {string[]} argv */
+export function parseArgs(argv) {
+  /** @type {{ gaps: boolean, refused: boolean, json: boolean, help: boolean, id?: string, siteType?: string, error?: string }} */
+  const args = { gaps: false, refused: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    if (key === "--list") continue;
+    if (key === "--gaps") { args.gaps = true; continue; }
+    if (key === "--refused") { args.refused = true; continue; }
+    if (key === "--json") { args.json = true; continue; }
+    if (key === "--help" || key === "-h") { args.help = true; continue; }
+    if (key === "--id" || key === "--site-type") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) return { ...args, error: `missing value for ${key}` };
+      if (key === "--id") args.id = value;
+      else args.siteType = value;
+      i += 1;
+      continue;
+    }
+    return { ...args, error: `unknown argument: ${key}` };
+  }
+  if (args.siteType && !SITE_TYPES.includes(args.siteType)) {
+    return { ...args, error: `--site-type must be one of: ${SITE_TYPES.join(", ")}` };
+  }
+  return args;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} _ctx
+ * @param {{ out?: (s: string) => void, err?: (s: string) => void }} [io]
+ */
+export function run(argv, _ctx, io = {}) {
+  const out = io.out ?? ((s) => process.stdout.write(s));
+  const err = io.err ?? ((s) => process.stderr.write(s));
+  const args = parseArgs(argv);
+  if (args.help) {
+    out(`${USAGE}\n`);
+    return 0;
+  }
+  if (args.error) {
+    err(`${args.error}\n\n${USAGE}\n`);
+    return 2;
+  }
+
+  if (args.id) {
+    const status = supportStatus(args.id);
+    if (args.json) {
+      const body = status.capability ? { ...status, capability: publicCapability(status.capability) } : status;
+      out(`${JSON.stringify(body, null, 2)}\n`);
+    } else {
+      out(`${describeCapability(args.id)}\n`);
+    }
+    return status.known ? 0 : 4;
+  }
+
+  let rows = capabilitiesFor(args.siteType);
+  if (args.gaps) rows = rows.filter((c) => c.tier === "not-yet");
+  if (args.refused) rows = rows.filter((c) => c.tier === "deliberately-refused");
+
+  if (args.json) {
+    out(`${JSON.stringify(rows.map(publicCapability), null, 2)}\n`);
+    return 0;
+  }
+
+  const width = Math.max(...rows.map((c) => c.id.length), 4);
+  for (const c of rows) out(`${TIER_MARK[c.tier] ?? c.tier}  ${c.id.padEnd(width)}  ${c.label}\n`);
+  out(
+    `\n${rows.length} of ${CAPABILITIES.length} capabilities`
+      + `${args.siteType ? ` for site type "${args.siteType}"` : ""}. `
+      + "Use --id <id> for what fills it, what proves it, and what to do about it.\n"
+      + "REFUSED means it will never be built — do not work around it locally.\n"
+      + "GAP means it is already filed — add evidence to that report rather than filing again.\n",
+  );
+  return 0;
+}