@port60/template-kit 0.12.0 → 0.14.0

package/bin/cli.mjs

@@ -10,6 +10,8 @@ import { model } from '../src/commands/model.mjs';
 import { content } from '../src/commands/content.mjs';
 import { upgrade } from '../src/commands/upgrade.mjs';
 import { refresh } from '../src/commands/refresh.mjs';
+import { login, logout, whoami } from '../src/commands/auth.mjs';
+import { publish } from '../src/commands/publish.mjs';
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -59,6 +61,18 @@ switch (command) {
   case 'package':
     await packageCmd(args);
     break;
+  case 'login':
+    await login(args);
+    break;
+  case 'logout':
+    await logout(args);
+    break;
+  case 'whoami':
+    await whoami(args);
+    break;
+  case 'publish':
+    await publish(args);
+    break;
   default:
     console.log(`@port60/template-kit, build Port60 site templates locally
 
@@ -73,6 +87,14 @@ usage:
   p60-template-kit package [dir]               validate + build the uploadable zip
   p60-template-kit upgrade [dir]               move an existing template to the latest kit
                                                and contract, re-brief, re-validate
+  p60-template-kit login                       sign in from the terminal (the browser does the
+                                               actual sign-in; the code appears here)
+  p60-template-kit whoami                      who is signed in, and which studio workspace
+  p60-template-kit logout                      sign this machine out and revoke its token
+  p60-template-kit publish [dir] [--no-submit] validate, package, upload to your studio and
+                                               submit for review, in one command
+  p60-template-kit publish [dir] --ci          the same from a GitHub Actions workflow: no
+                                               login, the run's own OIDC token is the credential
 
 AI agents: the scaffold's AGENTS.md is your briefing; iterate with \`validate --json\`.
 Docs: https://developers.port60.com (agents: /llms-full.txt)`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.12.0",
-  "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready — every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
+  "version": "0.14.0",
+  "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready \u2014 every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {
     "p60-template-kit": "bin/cli.mjs"
@@ -12,6 +12,7 @@
     "starter"
   ],
   "scripts": {
+    "sync-vendor": "node scripts/sync-vendor.mjs",
     "test": "node --test 'tests/*.test.mjs'"
   },
   "dependencies": {
@@ -22,12 +23,5 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Port60Labs/template-kit.git"
-  },
-  "homepage": "https://developers.port60.com",
-  "bugs": {
-    "url": "https://github.com/Port60Labs/template-kit/issues"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/commands/auth.mjs

@@ -0,0 +1,102 @@
+import { createInterface } from 'node:readline/promises';
+import {
+  accessToken, api, apiBase, authBase, authRealm, clearCredentials, decodeJwtPayload,
+  deviceLogin, loadCredentials, oauthClientId, requireCredentials, revoke, saveCredentials
+} from '../lib/auth.mjs';
+
+/**
+ * `login` / `logout` / `whoami` (developer CLI stream A). Login runs the device flow, then finds
+ * the developer's STUDIO workspace: memberships are product-blind, so the studio is discovered by
+ * probing the studio surface itself (the gateway's entitlement gate refuses non-studio workspaces,
+ * which is exactly the discriminator). One membership skips the ceremony; ambiguity asks once and
+ * the choice is remembered.
+ */
+
+async function studioProbe(creds, token, tenantId) {
+  try {
+    const res = await api(creds, token, `/api/admin/studio/tenants/${tenantId}/studio/status`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function login() {
+  const { accessToken: access, refreshToken } = await deviceLogin();
+  if (!refreshToken) {
+    console.error('✗ The sign-in completed but returned no offline token. Is offline_access enabled on the CLI client?');
+    process.exit(1);
+  }
+  const claims = decodeJwtPayload(access);
+  const creds = {
+    authBase: authBase(),
+    realm: authRealm(),
+    clientId: oauthClientId(),
+    apiBase: apiBase(),
+    refreshToken,
+    email: claims.email ?? null
+  };
+
+  const res = await api(creds, access, '/api/me/memberships');
+  if (!res.ok) {
+    console.error(`✗ Signed in, but the workspace list could not be read (${res.status}).`);
+    process.exit(1);
+  }
+  const memberships = await res.json();
+  if (memberships.length === 0) {
+    console.error('✗ This account has no workspaces. Create a developer account at https://port60.com/developers/ first.');
+    process.exit(1);
+  }
+
+  let workspace = null;
+  if (memberships.length === 1) {
+    workspace = memberships[0];
+  } else {
+    const probes = await Promise.all(
+      memberships.map(async (m) => ((await studioProbe(creds, access, m.tenantId)) ? m : null))
+    );
+    const studios = probes.filter(Boolean);
+    if (studios.length === 1) {
+      workspace = studios[0];
+    } else {
+      const candidates = studios.length > 0 ? studios : memberships;
+      console.log('\n  Your workspaces:');
+      candidates.forEach((m, i) => console.log(`    ${i + 1}. ${m.workspaceName}`));
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await rl.question('  Which one is your template studio? ');
+      rl.close();
+      workspace = candidates[Number(answer) - 1];
+      if (!workspace) {
+        console.error('✗ No such option. Run login again.');
+        process.exit(1);
+      }
+    }
+  }
+
+  saveCredentials({ ...creds, workspace: { tenantId: workspace.tenantId, name: workspace.workspaceName } });
+  console.log('');
+  console.log(`✓ Signed in${creds.email ? ` as ${creds.email}` : ''}.`);
+  console.log(`  Studio workspace: ${workspace.workspaceName}`);
+  console.log('  Not the account you meant? Run: p60-template-kit logout, then login again.');
+  console.log('  Publish from a template directory with: p60-template-kit publish');
+}
+
+export async function whoami() {
+  const creds = requireCredentials();
+  const token = await accessToken(creds);
+  const claims = decodeJwtPayload(token);
+  console.log(`Signed in as ${claims.email ?? creds.email ?? claims.sub}`);
+  console.log(`Studio workspace: ${creds.workspace?.name ?? '(none chosen)'}`);
+  console.log(`Platform API: ${creds.apiBase}`);
+}
+
+export async function logout() {
+  const creds = loadCredentials();
+  if (!creds) {
+    console.log('Not signed in.');
+    return;
+  }
+  await revoke(creds);
+  clearCredentials();
+  console.log('✓ Signed out; this machine\'s token has been revoked.');
+}

package/src/commands/create.mjs

@@ -42,7 +42,7 @@ export function create(args) {
   const briefing = agentsMd(name);
   writeFileSync(join(target, 'AGENTS.md'), briefing);
   writeFileSync(join(target, 'CLAUDE.md'), briefing);
-  writeFileSync(join(target, '.gitignore'), 'node_modules/\n*.zip\n');
+  writeFileSync(join(target, '.gitignore'), 'node_modules/\ndist/\n');
   writeFileSync(join(target, 'package.json'), JSON.stringify({
     name: `${name}-template`,
     private: true,
@@ -62,7 +62,7 @@ A Port60 site template. Start with \`npm install\`, then:
 
 - \`npm run dev\`, live preview at http://localhost:4400
 - \`npm run validate\`, conformance against the platform contract
-- \`npm run package\`, the uploadable zip
+- \`npm run package\`, the uploadable zip in \`dist/\` (recreated on every run)
 
 **Working with an AI agent?** Point it at this directory, \`AGENTS.md\` (and \`CLAUDE.md\`)
 brief it on the contract, the rules and the validate loop.

package/src/commands/packageCmd.mjs

@@ -1,4 +1,4 @@
-import { writeFileSync } from 'node:fs';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
@@ -7,7 +7,9 @@ import { buildZip } from '../lib/zip.mjs';
 /**
  * `package <dir>`, validate first (the platform will run the identical checks, so failing here
  * saves the round trip), then zip EXACTLY the contract-shaped file set into
- * `<name>-<version>.zip`, the artifact the studio's upload lane accepts as-is.
+ * `dist/<name>-<version>.zip`, the artifact the studio's upload lane accepts as-is. `dist/` is
+ * the build output and nothing else: recreated on every run, so a stale archive from a previous
+ * version can never sit beside the fresh one, and gitignored by the scaffold.
  */
 export async function packageCmd(args) {
   const dir = resolve(args._[0] ?? '.');
@@ -18,7 +20,10 @@ export async function packageCmd(args) {
     for (const e of errors) console.error(`  - ${e}`);
     process.exit(1);
   }
-  const out = join(dir, `${manifest.name}-${manifest.version}.zip`);
+  const outDir = join(dir, 'dist');
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir);
+  const out = join(outDir, `${manifest.name}-${manifest.version}.zip`);
   writeFileSync(out, buildZip(Object.entries(files).map(([path, content]) => ({ path, content }))));
   console.log(`✓ ${out}`);
   console.log('  Upload it from your studio (tenant admin → Studio → your template → Versions).');

package/src/commands/publish.mjs

@@ -0,0 +1,180 @@
+import { resolve } from 'node:path';
+import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+import { buildZip } from '../lib/zip.mjs';
+import { accessToken, api, apiBase, loadCredentials, requireCredentials } from '../lib/auth.mjs';
+
+/**
+ * `publish [dir]` (developer CLI stream A): validate, package and upload in one breath, then
+ * submit the version for review. The upload lane is manifest-routed, so an unclaimed name CREATES
+ * the template and a claimed one gains a version; the server runs the identical validation
+ * again, and a human reviews before anything can reach a charity's site. `--no-submit` stops at
+ * validated (submit later from the studio).
+ *
+ * `publish --ci` (stream B, docs/developer-cli-and-ci-publishing.md): the same validate and
+ * package steps, but inside GitHub Actions there is no person to sign in. The workflow's own
+ * OIDC token, minted by GitHub for the platform's audience, is the credential; the platform
+ * verifies GitHub's signature and the repository trust the developer registered in the studio.
+ * CI can add versions to a trusted template, never create one, and review still decides.
+ * Auto-detected inside Actions when this machine holds no stored login.
+ */
+export async function publish(args) {
+  // The CLI's parser reads `--flag value` greedily, so `publish --ci ./theme` would swallow the
+  // directory as the flag's value. Both flags here are booleans: hand a swallowed path back.
+  for (const flag of ['ci', 'no-submit']) {
+    if (typeof args[flag] === 'string') {
+      args._.unshift(args[flag]);
+      args[flag] = true;
+    }
+  }
+  const ci = args.ci === true || (process.env.GITHUB_ACTIONS === 'true' && !loadCredentials());
+  const creds = ci ? null : requireCredentials();
+  if (!ci && !creds.workspace?.tenantId) {
+    console.error('✗ No studio workspace on record. Run: p60-template-kit login');
+    process.exit(1);
+  }
+  const dir = resolve(args._[0] ?? '.');
+  const files = loadArtifactDir(dir);
+  const { errors, manifest } = await validateArtifact(files);
+  if (errors.length > 0) {
+    console.error(`✗ not publishing, ${errors.length} validation error${errors.length === 1 ? '' : 's'}:`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  const zip = buildZip(Object.entries(files).map(([path, content]) => ({ path, content })));
+  console.log(`✓ ${manifest.name} ${manifest.version} validated, uploading${ci ? ' from CI' : ''}…`);
+
+  if (ci) {
+    await publishFromCi(args, zip);
+    return;
+  }
+
+  const token = await accessToken(creds);
+  const studio = `/api/admin/studio/tenants/${creds.workspace.tenantId}/studio`;
+  const res = await api(creds, token, `${studio}/uploads`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/zip' },
+    body: zip
+  });
+  if (!res.ok) {
+    console.error(`✗ Upload refused (${res.status}): ${await errorMessage(res)}`);
+    if (res.status === 403) {
+      // The CLI holds the developer's OWN token; the server's permission model decides, exactly
+      // as in the studio UI. A role below the studio's minimum publishes nowhere.
+      console.error('  This account doesn\'t have permission to publish in that workspace.');
+      console.error('  Sign in with an account that administers the developer studio.');
+    }
+    process.exit(1);
+  }
+  const outcome = await res.json();
+  const upload = outcome.upload ?? {};
+  if (outcome.templateCreated) {
+    console.log(`✓ ${outcome.templateLabel} created from its manifest.`);
+  }
+  if (!printUpload(upload)) process.exit(1);
+
+  if (args['no-submit']) {
+    console.log('  Left unsubmitted (--no-submit). Submit it for review from your studio.');
+    return;
+  }
+
+  // Submission needs the version row's id; the detail read supplies it.
+  const detailRes = await api(creds, token, `${studio}/templates/${outcome.templateId}`);
+  if (!detailRes.ok) {
+    console.error(`⚠ Uploaded, but the submit step could not read the template (${detailRes.status}). Submit from your studio.`);
+    process.exit(1);
+  }
+  const detail = await detailRes.json();
+  const row = (detail.versions ?? []).find((v) => v.version === upload.version && v.status === 'VALIDATED');
+  if (!row) {
+    console.error('⚠ Uploaded, but the new version was not found in a submittable state. Submit from your studio.');
+    process.exit(1);
+  }
+  const submitRes = await api(creds, token, `${studio}/templates/${outcome.templateId}/versions/${row.id}/submit`, {
+    method: 'POST'
+  });
+  if (!submitRes.ok) {
+    console.error(`⚠ Uploaded, but submitting for review failed (${submitRes.status}). Submit from your studio.`);
+    process.exit(1);
+  }
+  console.log('✓ Submitted for review. You\'ll get an email when a reviewer decides.');
+}
+
+/** The audience the platform verifies; GitHub mints the token for exactly this value. */
+export const CI_AUDIENCE = () => process.env.P60_CI_AUDIENCE || 'port60-studio-ci';
+
+async function publishFromCi(args, zip) {
+  const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  if (!requestUrl || !requestToken) {
+    console.error('✗ publish --ci runs inside GitHub Actions, and the job needs the id-token permission:');
+    console.error('    permissions:');
+    console.error('      id-token: write');
+    console.error('      contents: read');
+    process.exit(1);
+  }
+  const oidc = await fetchActionsToken(requestUrl, requestToken, CI_AUDIENCE());
+
+  const submit = !args['no-submit'];
+  const res = await fetch(`${apiBase()}/api/public/studio/ci/publish?submit=${submit}`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${oidc}`, 'content-type': 'application/zip' },
+    body: zip
+  });
+  if (!res.ok) {
+    console.error(`✗ Publish refused (${res.status}): ${await errorMessage(res)}`);
+    if (res.status === 403) {
+      console.error('  Trust this repository under Automate publishing on the template in your studio,');
+      console.error('  and check the workflow runs from a ref the trust allows (refs/tags/v* by default).');
+    }
+    process.exit(1);
+  }
+  const result = await res.json();
+  console.log(`✓ ${result.templateName} accepted this run from ${result.repository} (${result.ref}).`);
+  if (!printUpload(result.upload ?? {})) process.exit(1);
+  if (result.submitted) {
+    console.log('✓ Submitted for review. The developer is emailed when a reviewer decides.');
+  } else if (!submit) {
+    console.log('  Left unsubmitted (--no-submit). Submit it for review from the studio.');
+  } else {
+    console.error(`⚠ Uploaded, but not submitted: ${result.submitDetail ?? 'submit from the studio.'}`);
+    process.exit(1);
+  }
+}
+
+/** GitHub's per-job token endpoint: the request URL already carries its query string. */
+async function fetchActionsToken(requestUrl, requestToken, audience) {
+  const url = `${requestUrl}${requestUrl.includes('?') ? '&' : '?'}audience=${encodeURIComponent(audience)}`;
+  const res = await fetch(url, { headers: { authorization: `Bearer ${requestToken}`, accept: 'application/json' } });
+  if (!res.ok) {
+    console.error(`✗ GitHub did not issue an OIDC token (${res.status}). Does the job have id-token: write?`);
+    process.exit(1);
+  }
+  const body = await res.json();
+  if (!body.value) {
+    console.error('✗ GitHub returned no token value.');
+    process.exit(1);
+  }
+  return body.value;
+}
+
+function printUpload(upload) {
+  if (!upload.accepted) {
+    console.error('✗ The platform rejected the version:');
+    for (const e of upload.errors ?? []) console.error(`  - ${e}`);
+    return false;
+  }
+  for (const w of upload.warnings ?? []) console.log(`  ⚠ ${w}`);
+  console.log(`✓ Version ${upload.version} uploaded and validated.`);
+  return true;
+}
+
+async function errorMessage(res) {
+  const text = await res.text();
+  try {
+    const body = JSON.parse(text);
+    return body.message ?? body.detail ?? text;
+  } catch {
+    return text;
+  }
+}

package/src/lib/auth.mjs

@@ -0,0 +1,195 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+/**
+ * The kit's sign-in plumbing (developer CLI stream A, docs/developer-cli-and-ci-publishing.md).
+ * The OAuth Device Authorization Grant against the platform's customer realm: the BROWSER does
+ * the actual sign-in (so passwordless email codes and Google both work unchanged), the terminal
+ * only ever holds the resulting tokens. The refresh token is an offline token, stored 0600 in
+ * ~/.port60/credentials.json and revocable from the account's sessions at any time.
+ */
+
+const STORE_DIR = join(homedir(), '.port60');
+const STORE_FILE = join(STORE_DIR, 'credentials.json');
+
+export const authBase = () => (process.env.P60_AUTH_BASE || 'https://auth.port60.com').replace(/\/+$/, '');
+export const authRealm = () => process.env.P60_REALM || 'port60-customers';
+export const apiBase = () => (process.env.P60_API_BASE || 'https://api.port60.com').replace(/\/+$/, '');
+export const oauthClientId = () => process.env.P60_CLIENT_ID || 'port60-kit';
+
+const tokenUrl = (base, realm) => `${base}/realms/${realm}/protocol/openid-connect/token`;
+
+export function loadCredentials() {
+  try {
+    return JSON.parse(readFileSync(STORE_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(creds) {
+  mkdirSync(STORE_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(STORE_FILE, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(STORE_FILE, 0o600); // writeFileSync mode is ignored when the file already exists
+}
+
+export function clearCredentials() {
+  rmSync(STORE_FILE, { force: true });
+}
+
+export function requireCredentials() {
+  const creds = loadCredentials();
+  if (!creds?.refreshToken) {
+    console.error('✗ Not signed in. Run: p60-template-kit login');
+    process.exit(1);
+  }
+  return creds;
+}
+
+/** The JWT payload, unverified — display only (email, subject). The server verifies for real. */
+export function decodeJwtPayload(token) {
+  try {
+    return JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function form(url, params) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(params)
+  });
+  const text = await res.text();
+  let body = {};
+  try {
+    body = JSON.parse(text);
+  } catch {
+    // non-JSON error page; the status carries the story
+  }
+  return { ok: res.ok, status: res.status, body };
+}
+
+/** A fresh access token from the stored offline token; rotates the stored refresh token when the
+ *  server hands a new one back. */
+export async function accessToken(creds) {
+  const { ok, status, body } = await form(tokenUrl(creds.authBase, creds.realm), {
+    grant_type: 'refresh_token',
+    client_id: creds.clientId,
+    refresh_token: creds.refreshToken
+  });
+  if (!ok) {
+    console.error(`✗ Your sign-in is no longer valid (${body.error ?? status}). Run: p60-template-kit login`);
+    process.exit(1);
+  }
+  if (body.refresh_token && body.refresh_token !== creds.refreshToken) {
+    saveCredentials({ ...creds, refreshToken: body.refresh_token });
+  }
+  return body.access_token;
+}
+
+function tryOpenBrowser(url) {
+  const opener = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(opener, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+  } catch {
+    // no browser to open; the printed URL is the path
+  }
+}
+
+const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
+
+/**
+ * The device flow itself: ask for a code, hand the human to the browser, poll until the sign-in
+ * completes. Returns {accessToken, refreshToken}.
+ */
+export async function deviceLogin() {
+  const base = authBase();
+  const realm = authRealm();
+  const clientId = oauthClientId();
+  // prompt=login forces a fresh, intentional sign-in at the verification page even when the
+  // browser already holds an SSO session — so a developer who is also signed in as (say) a charity
+  // editor can never silently authorise the CLI as the wrong account. Login is rare (the offline
+  // token lasts), so paying for intentionality every time is the right trade.
+  const start = await form(`${base}/realms/${realm}/protocol/openid-connect/auth/device`, {
+    client_id: clientId,
+    scope: 'openid offline_access',
+    prompt: 'login'
+  });
+  if (!start.ok) {
+    console.error(`✗ Could not start the sign-in (${start.body.error_description ?? start.body.error ?? start.status}).`);
+    if (start.status === 404 || start.body.error === 'invalid_client') {
+      console.error('  The sign-in service may not have the CLI client enabled yet.');
+    }
+    process.exit(1);
+  }
+  const { device_code: deviceCode, user_code: userCode, verification_uri: uri,
+    verification_uri_complete: uriComplete, interval = 5, expires_in: expiresIn = 600 } = start.body;
+
+  console.log('');
+  console.log(`  Visit:  ${uri}`);
+  console.log(`  Code:   ${userCode}`);
+  console.log('');
+  console.log('  Sign in there with the account you want to PUBLISH AS — you will be asked to sign in');
+  console.log('  even if your browser is already logged in, so pick the right one. This terminal will notice.');
+  if (uriComplete) tryOpenBrowser(uriComplete);
+
+  const deadline = Date.now() + expiresIn * 1000;
+  let waitSeconds = interval;
+  while (Date.now() < deadline) {
+    await sleep(waitSeconds);
+    const poll = await form(tokenUrl(base, realm), {
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      client_id: clientId,
+      device_code: deviceCode
+    });
+    if (poll.ok) {
+      return { accessToken: poll.body.access_token, refreshToken: poll.body.refresh_token };
+    }
+    switch (poll.body.error) {
+      case 'authorization_pending':
+        break;
+      case 'slow_down':
+        waitSeconds += 5;
+        break;
+      case 'access_denied':
+        console.error('✗ The sign-in was declined in the browser.');
+        process.exit(1);
+        break;
+      case 'expired_token':
+        console.error('✗ The code expired before the sign-in completed. Run login again.');
+        process.exit(1);
+        break;
+      default:
+        console.error(`✗ Sign-in failed (${poll.body.error_description ?? poll.body.error ?? poll.status}).`);
+        process.exit(1);
+    }
+  }
+  console.error('✗ The code expired before the sign-in completed. Run login again.');
+  process.exit(1);
+}
+
+/** Best-effort server-side revocation of the offline token; local removal always follows. */
+export async function revoke(creds) {
+  try {
+    await form(`${creds.authBase}/realms/${creds.realm}/protocol/openid-connect/logout`, {
+      client_id: creds.clientId,
+      refresh_token: creds.refreshToken
+    });
+  } catch {
+    // unreachable server; the local removal still signs this machine out
+  }
+}
+
+/** An authenticated platform-API call. */
+export async function api(creds, token, path, init = {}) {
+  const res = await fetch(`${creds.apiBase}${path}`, {
+    ...init,
+    headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) }
+  });
+  return res;
+}

package/src/vendor/contract/v1/tokens.json

@@ -14,7 +14,7 @@
     { "name": "--gold", "description": "Highlight tint (marks, ratings)." },
     { "name": "--marker", "description": "Impact-map pin colour (the live-map markers are a zoom-scaling circle layer that take this colour). Defaults to --accent." },
     { "name": "--map-mode", "description": "Impact-map basemap colour mode read by the map island: auto (derive the map's paper/ink from the theme), light, dark, or muted. Default auto." },
-    { "name": "--map-projection", "description": "Impact-map projection: flat (default) or globe — the planet as a rotatable sphere with atmosphere." },
+    { "name": "--map-projection", "description": "Impact-map projection: flat (default) or globe, the planet as a rotatable sphere with atmosphere." },
     { "name": "--line", "description": "Hairline borders." },
     { "name": "--line-strong", "description": "Emphasised borders (selected, focus)." },
     { "name": "--danger", "description": "Errors and destructive affordances." },

package/src/vendor/validator/platform-base.css

@@ -4339,6 +4339,24 @@ textarea.p60-form-control {
 .impact-map-card { margin-top: 14px; background: var(--surface); color: var(--ink);
   border: 1px solid var(--line); border-radius: var(--radius-sm); box-shadow: var(--shadow-sm);
   padding: 16px 18px; max-width: 34rem; }
+/* On the LIVE map the below-map card is a SMALL-SCREEN device: the anchored popup is taller than a
+   phone-height stage, so the marker selection drives this card instead (Google-Maps-mobile idiom).
+   Desktop keeps the inline popup and hides this. The pin-canvas fallback (no modifier) shows the
+   card on every screen size, as it always has. */
+.impact-map-card--small-screens { display: none; }
+@media (max-width: 640px) {
+  /* Full width, flush under the full-bleed map — the two read as one attached sheet (the same
+     breakout as the donate card; the hairline top border is the seam between map and card). */
+  .impact-map-card--small-screens {
+    display: block;
+    width: 100vw;
+    margin: 0 0 0 calc(50% - 50vw);
+    max-width: none;
+    border-radius: 0;
+    border-left: 0;
+    border-right: 0;
+  }
+}
 .impact-map-card-kind { display: inline-block; font-size: 11px; font-weight: 700;
   letter-spacing: 0.06em; text-transform: uppercase; color: var(--muted); margin-bottom: 4px; }
 .impact-map-card-title { margin: 0 0 6px; }