@port60/template-kit 0.13.0 → 0.14.1

package/bin/cli.mjs

@@ -93,6 +93,8 @@ usage:
   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,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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": {

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

@@ -2,18 +2,35 @@ 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, requireCredentials } from '../lib/auth.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
+ * 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.
+ * A trusted workflow does what a signed-in terminal does (a new name creates the template, an
+ * owned name gains a version); review still decides.
+ * Auto-detected inside Actions when this machine holds no stored login.
  */
 export async function publish(args) {
-  const creds = requireCredentials();
-  if (!creds.workspace?.tenantId) {
+  // 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);
   }
@@ -26,7 +43,12 @@ export async function publish(args) {
     process.exit(1);
   }
   const zip = buildZip(Object.entries(files).map(([path, content]) => ({ path, content })));
-  console.log(`✓ ${manifest.name} ${manifest.version} validated, uploading…`);
+  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`;
@@ -36,15 +58,7 @@ export async function publish(args) {
     body: zip
   });
   if (!res.ok) {
-    const text = await res.text();
-    let message = text;
-    try {
-      const body = JSON.parse(text);
-      message = body.message ?? body.detail ?? text;
-    } catch {
-      // plain-text error, shown as-is
-    }
-    console.error(`✗ Upload refused (${res.status}): ${message}`);
+    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.
@@ -58,13 +72,7 @@ export async function publish(args) {
   if (outcome.templateCreated) {
     console.log(`✓ ${outcome.templateLabel} created from its manifest.`);
   }
-  if (!upload.accepted) {
-    console.error('✗ The platform rejected the version:');
-    for (const e of upload.errors ?? []) console.error(`  - ${e}`);
-    process.exit(1);
-  }
-  for (const w of upload.warnings ?? []) console.log(`  ⚠ ${w}`);
-  console.log(`✓ Version ${upload.version} uploaded and validated.`);
+  if (!printUpload(upload)) process.exit(1);
 
   if (args['no-submit']) {
     console.log('  Left unsubmitted (--no-submit). Submit it for review from your studio.');
@@ -92,3 +100,85 @@ export async function publish(args) {
   }
   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 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();
+  if (result.templateCreated) {
+    console.log(`✓ ${result.templateLabel ?? result.templateName} created from its manifest.`);
+  }
+  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/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." },