@port60/template-kit 0.21.0 → 1.0.0

package/README.md

@@ -33,6 +33,8 @@ newer contract asks of you.
 | `dev [dir]` | Live preview over the contract's sample fixtures; validation re-runs on save. |
 | `validate [dir] [--json]` | The exact checks the platform runs at upload. `--json` emits `{ok, errors, warnings, provenSupports}`. |
 | `package [dir]` | Validate, then build the contract-shaped zip the studio accepts as-is. |
+| `release [dir]` | Build separate runtime and independent designer-preview folders for a trusted store release. Does not upload. |
+| `setup-previews [--with-deps]` | Install the pinned headless browser for automatic gallery images. Add `--with-deps` in Linux CI. |
 | `model [--json]` | The content model, in hand; `--json` for agents. |
 | `content [dir]` | Eject the model's data as your editable copy; render it with `dev --content`. |
 | `upgrade [dir]` | Latest kit + contract for an existing template; re-briefs and re-validates. |
@@ -48,9 +50,46 @@ See the [AI quickstart](https://developers.port60.com/guides/ai-quickstart/).
 
 ## The contract
 
-The vendored contract in `src/vendor/contract` is the **Charity Platform contract v1**, the
-platform's first product surface. The dialect, validation rules and this toolchain are
-platform-wide; future Port60 products ship their own contract packs for the same kit.
+Kit 1.0.0 authors **port60-liquid@2**, content model **2.0**, using the contract under
+`src/vendor/contract/v2`. Collection envelopes, independent header/footer navigation,
+resolved actions and page-scoped sections are explicit. V1 sources need a deliberate migration,
+not a manifest-only relabel. Historical v1 contracts remain frozen for existing platform pins.
+
+## Designer previews
+
+The scaffold creates `preview/config.json` and `preview/media/`. Optional `content` points to
+fictional v2 sample JSON relative to `preview/`; omission uses contract fixtures. `focus` is
+`none`, `donate` or `volunteer`. Use approved local JPEG, PNG or WebP images via
+`p60preview:filename.jpg` and retain provenance with the source. Never use selecting-tenant data.
+
+`npm run release` writes `dist/release/NAME/VERSION/`: lightweight `template/` files, separate
+`preview/` HTML/media/metadata, and a `release.json` completion record. Every Look is generated
+from actual Liquid/CSS with matching palettes. Existing output is refused. Limits are 24 Looks,
+2 MiB per image/page and 24 MiB per release. Demo forms, navigation and transactions are inactive.
+
+The first-party publisher uploads completion last. The catalogue supplies matching preview
+metadata to tenant-admin; charity-site reads only runtime files. Previews are not bundled into
+admin and do not become tenant content. Preview-only changes also need a new template version.
+The Studio ZIP `package`/`publish` path remains separate and runtime-only.
+
+Before your first release build, run `npm run preview:setup` in a new scaffold, or
+`p60-template-kit setup-previews` in an existing project. Repeat after upgrading the kit.
+The release builder automatically captures each Look from the actual template at 1440x900
+and writes a 960x600 WebP to `preview/gallery/`, capped at 160 KiB. No separate screenshot
+authoring or upload is needed. The gallery uses these images; opening a design loads its HTML.
+The pinned browser is a build dependency only, never part of the live website.
+
+Linux capture requires a working Chromium sandbox. Ubuntu 24.04 hosted CI installs the
+repository's browser-path-scoped AppArmor profile to allow its user namespaces.
+No `--no-sandbox` or global AppArmor disablement is used. On another Linux
+host, configure an administrator-approved sandbox according to
+[Chromium's guidance](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md).
+Browser installation alone does not change the host's security policy.
+
+Only packaged preview assets and fonts.bunny.net are accessible during capture. Failed required
+imagery or Latin fonts stop generation. Arabic-specific poster font fidelity is deferred;
+full previews and live-site typography are unchanged. Preserve the same kit/browser/OS for
+immutable upload retries; output changes need a new version, not an overwrite.
 
 Full documentation: [developers.port60.com](https://developers.port60.com)
 

package/bin/cli.mjs

@@ -12,6 +12,8 @@ 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';
+import { releaseCmd } from '../src/commands/release.mjs';
+import { setupPreviews } from '../src/commands/setupPreviews.mjs';
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -37,6 +39,12 @@ const [command, ...rest] = process.argv.slice(2);
 const args = parseArgs(rest);
 
 switch (command) {
+  case 'setup-previews':
+    setupPreviews(args);
+    break;
+  case 'release':
+    await releaseCmd(args);
+    break;
   case 'create':
     create(args);
     break;
@@ -85,6 +93,8 @@ usage:
   p60-template-kit content [dir] [--out file]  eject the model's data as your editable copy
   p60-template-kit validate [dir] [--json]     the platform's exact conformance checks
   p60-template-kit package [dir]               validate + build the uploadable zip
+  p60-template-kit release [dir]               build separate template/ and preview/ store bundles
+  p60-template-kit setup-previews [--with-deps] install the release builder's headless browser
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.21.0",
+  "version": "1.0.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.",
   "type": "module",
   "bin": {
@@ -16,8 +16,10 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
+    "jsdom": "29.1.1",
     "liquidjs": "^10.27.2",
-    "lucide-static": "^1.41.0"
+    "lucide-static": "^1.41.0",
+    "playwright": "1.63.0"
   },
   "license": "MIT",
   "repository": {

package/src/commands/content.mjs

@@ -1,6 +1,6 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { buildSiteFixture, composePage, validatePreviewContent } from '../vendor/validator/site-context.mjs';
+import { buildSiteFixture, composePage, validatePreviewContent } from '../vendor/validator/site-context-v2.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**
@@ -34,9 +34,10 @@ export function content(args) {
   }
   const data = {
     brand: site.brand,
-    nav: { items: site.nav?.items ?? [] },
+    nav: site.nav,
+    actions: site.actions,
     ...(manifest ? { pages: { home: composePage(manifest, 'home'), about: composePage(manifest, 'about') } } : {}),
-    ...Object.fromEntries(Object.entries(site.content).filter(([name]) => name !== 'about'))
+    ...site.content
   };
   const problems = validatePreviewContent(data);
   if (problems.length > 0) {

package/src/commands/create.mjs

@@ -19,7 +19,7 @@ export function create(args) {
   const name = (args.name ?? basename(target)).toLowerCase();
   if (!NAME_PATTERN.test(name)) {
     console.error(`✗ '${name}' is not a valid template name (lowercase letters, digits, hyphens, `
-        + '3–50 chars, starting with a letter). Pass --name.');
+        + '3 to 50 chars, starting with a letter). Pass --name.');
     process.exit(1);
   }
   if (existsSync(join(target, 'manifest.json'))) {
@@ -50,7 +50,9 @@ export function create(args) {
       dev: 'p60-template-kit dev .',
       validate: 'p60-template-kit validate .',
       'validate:json': 'p60-template-kit validate . --json',
-      package: 'p60-template-kit package .'
+      package: 'p60-template-kit package .',
+      release: 'p60-template-kit release .',
+      'preview:setup': 'p60-template-kit setup-previews'
     },
     devDependencies: {
       '@port60/template-kit': `^${KIT_PACKAGE.version}`
@@ -58,11 +60,17 @@ export function create(args) {
   }, null, 2) + '\n');
   writeFileSync(join(target, 'README.md'), `# ${label}
 
-A Port60 site template. Start with \`npm install\`, then:
+A Port60 site template using \`port60-liquid@2\`, content model \`2.0\` and kit \`1.0.0\`.
+Existing v1 platform pins keep historical support; this kit accepts v2 authoring only.
+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 in \`dist/\` (recreated on every run)
+- \`npm run release\`, separate runtime and designer-preview folders in \`dist/release/\`
+- \`npm run preview:setup\`, install the pinned browser before your first release build
+- \`preview/config.json\` selects author sample content and widget state; put optional
+  author images in \`preview/media/\` and reference them as \`p60preview:filename.jpg\`.
 
 **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/dev.mjs

@@ -3,9 +3,9 @@ import { watch, readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { surfaceFor, knobOverridesFromQuery, previewAssetPath, previewAssetType } from '../lib/previewOptions.mjs';
 import { renderStudioPreview } from '../vendor/validator/preview.mjs';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
-import { applyPreviewContent, buildSiteFixture, validatePreviewContent } from '../vendor/validator/site-context.mjs';
-import { renderModelReferenceHtml } from '../vendor/validator/model-reference.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
+import { applyPreviewContent, buildSiteFixture, validatePreviewContent } from '../vendor/validator/site-context-v2.mjs';
+import { renderModelReferenceHtml } from '../vendor/validator/model-reference-v2.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 import { join } from 'node:path';
 
@@ -80,6 +80,12 @@ function imageOriginsOf(json) {
  */
 export async function dev(args) {
   const dir = resolve(args._[0] ?? '.');
+  const initialManifest = JSON.parse(loadArtifactDir(dir)['manifest.json'] ?? '{}');
+  if (initialManifest.format !== 'port60-liquid@2') {
+    console.error('✗ Kit 1.0.0 requires port60-liquid@2. Existing v1 pins remain supported by the platform, not by the new authoring kit.');
+    process.exitCode = 1;
+    return;
+  }
   const port = Number(args.port ?? 4400);
   // The dev-richer half of the imagery split: point P60_FIXTURE_IMAGES at the platform's fixture
   // imagery base and the preview loads photographic fixtures from that ONE origin instead of the

package/src/commands/model.mjs

@@ -1,4 +1,4 @@
-import { contentModel } from '../vendor/engine/content-footprint.mjs';
+import { contentModelV2 as contentModel } from '../vendor/engine/content-footprint.mjs';
 
 /**
  * `model [--json]`, the content model, in hand. Prints every `site.content.*` collection with
@@ -15,7 +15,7 @@ export function model(args) {
   console.log('site also carries: ' + contentModel.siblings.keys.map((k) => `site.${k}`).join(', '));
   console.log('');
   for (const [name, collection] of Object.entries(contentModel.collections)) {
-    const more = collection.moreHref ? ` · more at ${collection.moreHref}` : '';
+    const more = collection.shape === 'envelope' ? ' · {label, href, items, pagination}' : ' · array';
     console.log(`site.content.${name}  (bounded at ${collection.cap}${more}, since ${collection.since})`);
     for (const [field, spec] of Object.entries(collection.item)) {
       const notes = [
@@ -27,7 +27,7 @@ export function model(args) {
     }
     console.log('');
   }
-  console.log('Rules: collections are bounded (link onward via moreHref); enums are open (branch and');
+  console.log('Rules: collections are bounded (link onward via href and pagination); enums are open (branch and');
   console.log('fall back); nullable fields need a branch; the model only grows. Your footprint and');
   console.log('minimum model version are computed at publish, you never declare them. Live examples:');
   console.log('the /model page on your dev preview.');

package/src/commands/packageCmd.mjs

@@ -1,6 +1,6 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 

package/src/commands/publish.mjs

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 import { accessToken, api, apiBase, loadCredentials, requireCredentials } from '../lib/auth.mjs';

package/src/commands/refresh.mjs

@@ -2,9 +2,9 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { agentsMd } from '../lib/agentsMd.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
-import { contentModel } from '../vendor/engine/content-footprint.mjs';
-import dialect from '../vendor/contract/v1/dialect.json' with { type: 'json' };
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
+import { contentModelV2 as contentModel } from '../vendor/engine/content-footprint.mjs';
+import dialect from '../vendor/contract/v2/dialect.json' with { type: 'json' };
 
 const KIT_PACKAGE = JSON.parse(
   readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8')
@@ -25,6 +25,11 @@ export async function refresh(args) {
     process.exit(1);
   }
   const manifest = JSON.parse(files['manifest.json']);
+  if (manifest.format !== dialect.format) {
+    console.error(`✗ Kit ${KIT_PACKAGE.version} requires ${dialect.format}. Migrate the template before refreshing its instructions. No files changed.`);
+    process.exitCode = 1;
+    return;
+  }
 
   const briefing = agentsMd(manifest.name);
   writeFileSync(join(dir, 'AGENTS.md'), briefing);

package/src/commands/release.mjs

@@ -0,0 +1,22 @@
+import { mkdirSync, writeFileSync, existsSync, lstatSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { buildReleaseBundle } from '../lib/releaseBundle.mjs';
+
+export async function releaseCmd(args) {
+  const root = resolve(args._[0] ?? '.');
+  const bundle = await buildReleaseBundle(root);
+  const output = join(root, 'dist', 'release', bundle.manifest.name, bundle.manifest.version);
+  // Never follow a linked build destination or silently mix two builds of an immutable release.
+  for (const dir of [join(root, 'dist'), join(root, 'dist', 'release'), join(root, 'dist', 'release', bundle.manifest.name), output]) {
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error('Linked release destination refused');
+  }
+  if (existsSync(output)) throw new Error(`Release output already exists: ${output}. Review/remove that generated directory or bump the version before rebuilding.`);
+  for (const [path, file] of Object.entries(bundle.files)) {
+    const destination = join(output, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, file.bytes, { flag: 'wx' });
+  }
+  console.log(`Validated release: ${output}`);
+  console.log('template/ is runtime only; preview/ is the independent designer gallery. Publish release.json last.');
+  console.log('Studio package/publish still accepts the runtime ZIP; store release publication uses the first-party pipeline.');
+}

package/src/commands/setupPreviews.mjs

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+
+export function previewSetupCommand(args = {}) {
+  const require = createRequire(import.meta.url);
+  // Playwright exports its manifest, not a ./cli module. Use its declared binary so
+  // this resolves the kit's pinned installation even inside another npm project.
+  const manifestPath = require.resolve('playwright/package.json');
+  const command = [resolve(dirname(manifestPath), require(manifestPath).bin.playwright), 'install', 'chromium', '--only-shell'];
+  if (args['with-deps']) command.push('--with-deps');
+  return command;
+}
+
+export function setupPreviews(args) {
+  const result = spawnSync(process.execPath, previewSetupCommand(args), { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}

package/src/commands/validate.mjs

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**