@port60/template-kit 0.14.2 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "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/packageCmd.mjs

@@ -1,7 +1,7 @@
 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';
+import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 
 /**
@@ -9,7 +9,8 @@ import { buildZip } from '../lib/zip.mjs';
  * saves the round trip), then zip EXACTLY the contract-shaped file set into
  * `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.
+ * version can never sit beside the fresh one, and gitignored by the scaffold. Anything the rules
+ * left out (an image in assets/, a stray script) is listed under the result, never silently.
  */
 export async function packageCmd(args) {
   const dir = resolve(args._[0] ?? '.');
@@ -26,5 +27,6 @@ export async function packageCmd(args) {
   const out = join(outDir, `${manifest.name}-${manifest.version}.zip`);
   writeFileSync(out, buildZip(Object.entries(files).map(([path, content]) => ({ path, content }))));
   console.log(`✓ ${out}`);
+  for (const line of skippedNotice(dir)) console.log(line);
   console.log('  Upload it from your studio (tenant admin → Studio → your template → Versions).');
 }

package/src/commands/publish.mjs

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path';
 import { validateArtifact } from '../vendor/validator/validate.mjs';
-import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 import { accessToken, api, apiBase, loadCredentials, requireCredentials } from '../lib/auth.mjs';
 
@@ -44,6 +44,7 @@ export async function publish(args) {
   }
   const zip = buildZip(Object.entries(files).map(([path, content]) => ({ path, content })));
   console.log(`✓ ${manifest.name} ${manifest.version} validated, uploading${ci ? ' from CI' : ''}…`);
+  for (const line of skippedNotice(dir)) console.log(line);
 
   if (ci) {
     await publishFromCi(args, zip);

package/src/lib/agentsMd.mjs

@@ -34,8 +34,11 @@ platform accepts it; if it fails here, the upload will fail identically.
   \`supports.sections\`. Charities compose pages from a **closed catalogue** of section types
   (see \`npm run validate\` output or the docs), you cannot invent new types.
 - \`pages/<page>.liquid\`, optional full-page templates for \`supports.pageTemplates\`.
-- \`assets/theme.css\`, required, your entire look. More \`.css\` files under \`assets/\` are
-  allowed. **No images, no JS**, they are refused at upload.
+- \`assets/theme.css\`, required, your entire look, and the ONLY stylesheet the platform loads
+  (other \`.css\` files under \`assets/\` are packaged but never loaded, so keep everything in
+  it). **No images, no fonts, no JS**: \`package\` and \`publish\` leave them out and list what
+  they left out; the upload refuses them. Photographs belong in the charity's media library;
+  decorative textures go inline in the CSS as data URIs.
 
 ## The rules the validator enforces (do not fight them)
 

package/src/lib/artifactFiles.mjs

@@ -1,4 +1,4 @@
-// The contract-shaped file set of an artifact directory — the same selection the platform's
+// The contract-shaped file set of an artifact directory, the same selection the platform's
 // upload intake allow-lists: manifest, layout, section/page renderers, css assets. Anything else
 // in the directory is not part of an artifact and is neither validated nor packaged.
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
@@ -26,3 +26,43 @@ export function loadArtifactDir(root) {
   }
   return files;
 }
+
+// What the artifact rules leave behind. A photograph, a font or a script dropped next to the
+// renderers is the classic surprise: it may even show in a local page, then the zip and the upload
+// carry nothing of it. `package` and `publish` print this list so the author learns it from the
+// kit, not from a broken URL on a live site. Project files that legitimately live beside a
+// template (README, package.json, node_modules, dist, preview content, design notes) are not
+// reported; only the three artifact folders and top-level binaries are.
+const ACCEPTED = { sections: /\.liquid$/, pages: /\.liquid$/, assets: /\.css$/ };
+const TOP_LEVEL_BINARY = /\.(png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|otf|eot|mp4|webm|mp3|m4a|js|mjs|cjs|ts)$/i;
+
+export function listSkippedFiles(root) {
+  const skipped = [];
+  const walk = (dir, rel, accept, depth) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const path = `${rel}/${entry.name}`;
+      if (entry.isDirectory()) walk(join(dir, entry.name), path, accept, depth + 1);
+      // Only the folder's own files are read; anything nested is left out whatever its name.
+      else if (depth > 0 || !accept.test(entry.name)) skipped.push(path);
+    }
+  };
+  for (const [dir, accept] of Object.entries(ACCEPTED)) {
+    if (existsSync(join(root, dir))) walk(join(root, dir), dir, accept, 0);
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isFile() && TOP_LEVEL_BINARY.test(entry.name)) skipped.push(entry.name);
+  }
+  return skipped.sort();
+}
+
+/** The lines `package`/`publish` print under the result when something was left out; empty otherwise. */
+export function skippedNotice(root) {
+  const skipped = listSkippedFiles(root);
+  if (skipped.length === 0) return [];
+  return [
+    `  left out (not part of a template): ${skipped.join(', ')}`,
+    '  Templates ship Liquid and CSS only; photographs belong in the charity\'s media library.',
+    '  See https://developers.port60.com/guides/publishing/#what-the-zip-contains'
+  ];
+}