parley-live 0.5.0 → 0.5.1

package/dist/index.js

@@ -18,7 +18,7 @@ import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node
 import path from 'node:path';
 import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, loadLast, openInBrowser, rememberLast, resolveRef, saveCredentials, sleep, } from './client.js';
 import { cmdLens, LensError } from './lens.js';
-const VERSION = '0.5.0';
+const VERSION = '0.5.1';
 /** Server advice written for Parley's in-app agent names its tools; a CLI user
  *  has commands instead, so the same advice is re-spoken in CLI terms. */
 function humanizeServerMessage(message) {
@@ -1005,7 +1005,7 @@ function help(topic) {
         engines: 'parley engines\n  Which video engines this server can run right now and their credit rates.',
         'camera-moves': 'parley camera-moves\n  The named camera-move presets accepted by `parley video --move`.',
         account: 'parley account\n  Your credit balance.',
-        lens: 'parley lens <status|connect|build|describe|record|metrics>\n  Build a Snap Specs Lens on this computer through Lens Studio: a step-by-step training guide with pinch buttons and optional voice shortcuts, tested in the preview before you see it. "describe" turns plain language into steps (about a cent, billed to your credits); "build <form.json>" is free. Run `parley lens status` first: it tells you exactly what to set up.',
+        lens: 'parley lens <status|connect|build|describe|publish|record|metrics>\n  Build a Snap Specs Lens on this computer through Lens Studio: a step-by-step training guide with pinch buttons and optional voice shortcuts, tested in the preview before you see it. "describe" turns plain language into steps (about a cent, billed to your credits); "build <form.json>" is free. Run `parley lens status` first: it tells you exactly what to set up. `publish` runs Snap\u0027s own preflight and SnapOS Package export (needs Lens Studio signed in).',
     };
     if (topic && lines[topic]) {
         console.log(lines[topic]);

package/dist/lens.js

@@ -7,6 +7,7 @@
  *   parley lens connect --config '<json>'   Save the config Lens Studio copies (AI Assistant > MCP > Configure Server)
  *   parley lens build <form.json>           Form -> tested Lens ($0, no model call)
  *   parley lens describe "<procedure>"      Plain language -> steps (billed, about a cent) -> tested Lens
+ *   parley lens publish [<lens id>]        Snap's preflight, then Snap's SnapOS Package export
  *   parley lens record <run> [--on-glasses passed|issues] [--published submitted|published]
  *   parley lens metrics
  */
@@ -198,6 +199,35 @@ export async function cmdLens(positionals, flags, jsonMode) {
             throw new LensError('The build did not pass. Read the report.', 6);
         return;
     }
+    if (sub === 'publish') {
+        const target = positionals[1];
+        const events = await runPipeline('publish', { target }, (e) => { if (!jsonMode && e.type === 'log')
+            console.log('  ' + e.message); });
+        const r = events[events.length - 1];
+        if (r.type === 'error')
+            throw new LensError(r.error, 1);
+        out(r, () => {
+            console.log('');
+            console.log(`Lens name for Snap: ${r.lensName ?? '(unknown)'}`);
+            console.log(`Name, icon and signing key on the project: ${r.readyLocally ? 'all set' : 'incomplete'}`);
+            if (r.issues?.length)
+                for (const i of r.issues)
+                    console.log('  - ' + i);
+            if (r.ok) {
+                console.log(`\nSnapOS Package exported: ${r.spkPath}`);
+                if (r.bytes)
+                    console.log(`${r.bytes} bytes${r.checksum ? ', checksum ' + r.checksum : ''}`);
+            }
+            else if (r.stage === 'blocked_on_sign_in') {
+                console.log('\nNot packaged: Lens Studio is not signed in.');
+            }
+            for (const n of r.next ?? [])
+                console.log('\n' + n);
+        });
+        if (!r.ok)
+            throw new LensError(r.stage === 'blocked_on_sign_in' ? 'Sign in to Lens Studio, then run this again.' : 'The Lens was not packaged.', r.stage === 'blocked_on_sign_in' ? 2 : 6);
+        return;
+    }
     if (sub === 'record') {
         const run = positionals[1];
         const hw = str(flags['on-glasses']);
@@ -218,5 +248,5 @@ export async function cmdLens(positionals, flags, jsonMode) {
             console.log('No Lenses built on this computer yet.'); });
         return;
     }
-    throw new LensError(`Unknown: parley lens ${sub}. Use status | connect | build | describe | record | metrics.`, 64);
+    throw new LensError(`Unknown: parley lens ${sub}. Use status | connect | build | describe | publish | record | metrics.`, 64);
 }

package/lens-builder/build.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { Bridge, ROOT, DATA } from './lib/bridge.mjs';
 import { compile } from './training/compile.mjs';
 import { verify } from './verify.mjs';
+import { prepareSubmission } from './lib/submission.mjs';
 
 const MAX_ITERATIONS = 5;
 const here = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
@@ -35,8 +36,10 @@ export async function build(form, { log = console.log, planner = null } = {}) {
     await bridge.connect();
     const project = await bridge.newProject(lens_id);
     log(`project: ${project.esproj}`);
+
     await bridge.specsPreview();
 
+    let submission = null;
     let report = null;
     for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
       result.iterations = iteration;
@@ -44,9 +47,19 @@ export async function build(form, { log = console.log, planner = null } = {}) {
       const authored = await bridge.eecFile(path.join(here, 'training', 'author-scene.ts'), { layout, scriptPath: scriptPath.split(path.sep).join('/') }, 90000);
       log(`iteration ${iteration}: authored ${authored.created.length} objects, script ${authored.script.mode}`);
 
+      // Snap will not take a Lens without a name it accepts, an icon and a production signing key.
+      // A project copied from Snap's Base Template arrives called "SpecsBaseTemplate"; left alone, that is
+      // the name that would reach Snap. Done after authoring, not straight after the project opens:
+      // writing metadata while Snap's UIKit package is still importing left the package half-resolved
+      // (its own textures then failed to load at runtime).
+      if (!submission) {
+        submission = await prepareSubmission(bridge, { projectDir: project.dir, procedureName: form.procedureName, lensName: form.lensName });
+        log(`for Snap: name "${submission.lensName}", icon set, signing key ${submission.signingKeyCreated ? 'generated' : 'reused'}`);
+      }
+
       // ---- Verifier
       result.stage = 'verify';
-      report = await verify({ bridge, plan, form, runDir, iteration, projectDir: project.dir });
+      report = await verify({ bridge, plan, form, runDir, iteration, projectDir: project.dir, submission });
       fs.writeFileSync(path.join(runDir, 'verifier', `iteration-${iteration}.json`), JSON.stringify(report, null, 2));
       for (const c of report.checks) log(`  ${c.status.toUpperCase().padEnd(8)} ${c.item}${c.detail ? '  -> ' + String(c.detail).slice(0, 160) : ''}`);
       if (report.pass) break;
@@ -62,7 +75,8 @@ export async function build(form, { log = console.log, planner = null } = {}) {
     result.stage = result.ok ? 'done' : 'escalated';
     result.seconds = Math.round((Date.now() - started) / 1000);
     result.costUsd = planner ? planner.costUsd : 0;
-    fs.writeFileSync(path.join(runDir, 'report.md'), renderReport({ plan, form, report, result, project, planner }));
+    result.submission = submission;
+    fs.writeFileSync(path.join(runDir, 'report.md'), renderReport({ plan, form, report, result, project, planner, submission }));
     fs.writeFileSync(path.join(runDir, 'metrics.json'), JSON.stringify({ lens_id, title: plan.title, vertical: plan.vertical, source: planner ? 'prompt' : 'form', prompt: planner ? planner.prompt : null, pass: result.ok, iterations: result.iterations, seconds: result.seconds + (planner ? planner.seconds : 0), costUsd: result.costUsd, tokens: planner ? planner.usage : { input: 0, output: 0, calls: 0 }, steps: form.steps.length, hardwareItems: report.checks.filter((c) => c.status === 'hardware').length, hardwareTest: 'not tested', publishStatus: 'not published', finished_at: new Date().toISOString() }, null, 2));
     return { ...result, report };
   } catch (e) {
@@ -73,7 +87,7 @@ export async function build(form, { log = console.log, planner = null } = {}) {
   }
 }
 
-function renderReport({ plan, form, report, result, project, planner }) {
+function renderReport({ plan, form, report, result, project, planner, submission }) {
   const line = (c) => `| ${c.status === 'pass' ? 'PASS' : c.status === 'fail' ? 'FAIL' : 'NEEDS HARDWARE'} | ${c.item} | ${String(c.detail ?? '').replace(/\|/g, '/').slice(0, 220)} |`;
   const cost = planner
     ? `USD ${planner.costUsd.toFixed(4)} (${planner.usage.input} in / ${planner.usage.output} out tokens, ${planner.model}, planning took ${planner.seconds}s)`
@@ -111,12 +125,17 @@ Source: https://developers.snap.com/spectacles/get-started/start-building/publis
 **Tests performed (preview):**
 ${report.checks.filter((c) => c.status === 'pass').map((c) => `- ${c.item}`).join('\n')}
 
+**Lens name:** ${submission.lensName} (Snap accepts at most 18 characters; the full procedure name stays on the panel)
+**Lens icon:** set, 320x320 PNG
+**Signing key:** production key attached to the project
+
 **Tests Snap should repeat on device:** open the Lens, confirm "v${form.version || '1.0.0'}" shows under the buttons, pinch Done through all ${form.steps.length} step${form.steps.length === 1 ? '' : 's'} to the completion message, pinch Back once from step 2${form.voiceShortcuts !== false ? ', say "done" to advance' : ''}.
 
 ## Manual steps remaining
 - Put the Lens on glasses: pair Specs in Lens Studio, then Send to Spectacles.
 - Check frame rate and thermals on device with the Lens Performance Overlay (Snap targets 60 FPS).
-- Add a custom icon and a preview image or video in Project Info, then Publish in Lens Studio (not automated yet).
+- Sign in to Lens Studio (My Lenses > Login). That is the one thing Parley cannot do for you, and it gates Snap's preflight, the SnapOS Package export and the upload.
+- Add a preview image or video, then run the publish steps. Name, icon and signing key are already set on this project.
 `;
 }
 

package/lens-builder/cli.mjs

@@ -3,6 +3,7 @@
 //   node lens-builder/cli.mjs plan   < {"prompt":""}  -> { type:'planner', decision, form|question|reason, costUsd }
 //   node lens-builder/cli.mjs build  < {"form":{}, "planner":{}?} -> progress events, then { type:'result', ... }
 //   node lens-builder/cli.mjs metrics                -> { type:'metrics', lenses:[...] }
+//   node lens-builder/cli.mjs publish [lensId|run]     -> Snap preflight + SnapOS Package export (needs Lens Studio sign-in)
 //   node lens-builder/cli.mjs record < {"run":"","hardwareTest":"","publishStatus":"","notes":""} -> updated metrics row
 import fs from 'node:fs';
 import path from 'node:path';
@@ -75,6 +76,11 @@ try {
   if (cmd === 'status') await status();
   else if (cmd === 'metrics') metrics();
   else if (cmd === 'record') await record();
+  else if (cmd === 'publish') {
+    const { publish } = await import('./publish.mjs');
+    const { target } = await readStdin();
+    emit({ type: 'publish', ...(await publish(target, { log: (message) => emit({ type: 'log', message }) })) });
+  }
   else if (cmd === 'plan') {
     const { planFromPrompt } = await import('./planner.mjs');
     const { prompt, auth } = await readStdin();

package/lens-builder/lib/bridge.mjs

@@ -83,6 +83,19 @@ export class Bridge {
     return out.returnValue;
   }
 
+  // Run a script that lives on disk by PATH, without reading it into this process. Snap's publish
+  // scripts are meant to run this way (preflight.ts alone is ~28 KB, and reading it costs that twice).
+  async eecPath(file, args = {}, timeoutMs = 120000) {
+    const out = await this.call('ExecuteEditorCode', { path: file.split(path.sep).join('/'), args, timeoutMs });
+    if (out.status !== 'Execution Succeeded') {
+      const detail = (out.errors || []).join(' ') || out.error || JSON.stringify(out).slice(0, 800);
+      const err = new Error(`${path.basename(file)}: ${out.status}: ${detail}`);
+      err.details = out;
+      throw err;
+    }
+    return out.returnValue;
+  }
+
   eecFile(file, args = {}, timeoutMs = 60000) {
     return this.eec(fs.readFileSync(file, 'utf8'), args, timeoutMs);
   }

package/lens-builder/lib/submission.mjs

@@ -0,0 +1,246 @@
+// Everything Snap requires of a Lens before it can be submitted, done at build time.
+//
+// Three of the four requirements can be met on this computer with no Snap account:
+//   - a valid Lens name. Snap's Editor.Model.MetaInfo.isLensNameValid accepts at most 18 characters
+//     (probed against Lens Studio 5.24.0: 18 ok, 19 rejected; spaces, digits, - : & ' all fine,
+//     trailing space rejected). A project copied from Snap's Base Template arrives named
+//     "SpecsBaseTemplate", which is what would otherwise reach Snap.
+//   - a 320x320 PNG Lens icon (the size Snap's own generate-lens-icon.py produces). Written here
+//     with zlib alone so it works from the desktop app and from the npm CLI with no extra dependency.
+//   - a production signing key, which Snap's own signing-key.js makes from Node built-ins.
+//
+// The fourth, being signed in to Lens Studio, is Snap's gate: it blocks their preflight, the SPK
+// export and every authorized call. Nothing here pretends to work around it.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import crypto from 'node:crypto';
+
+export const SNAP_LENS_NAME_MAX = 18;
+const TRAILING_FILLER = new Set(['and', 'or', 'the', 'a', 'an', 'of', 'for', 'to', 'with', 'on', 'in', 'at', 'by', 'per']);
+
+/** A Lens name Snap will accept, derived from the procedure name. Deterministic. */
+export function snapLensName(procedureName, override) {
+  const clean = (s) => String(s || '').replace(/[^A-Za-z0-9 \-:&']/g, ' ').replace(/\s+/g, ' ').trim();
+  if (override) {
+    const o = clean(override);
+    if (o && o.length <= SNAP_LENS_NAME_MAX) return o;
+  }
+  const words = clean(procedureName).split(' ').filter(Boolean);
+  if (!words.length) return 'Parley Guide';
+  const kept = [];
+  for (const w of words) {
+    const next = kept.length ? `${kept.join(' ')} ${w}` : w;
+    if (next.length > SNAP_LENS_NAME_MAX) break;
+    kept.push(w);
+  }
+  while (kept.length > 1 && TRAILING_FILLER.has(kept[kept.length - 1].toLowerCase())) kept.pop();
+  const name = kept.join(' ').trim();
+  if (name) return name;
+  return clean(procedureName).slice(0, SNAP_LENS_NAME_MAX).trim() || 'Parley Guide';
+}
+
+// ---------------------------------------------------------------- 320x320 PNG, no dependencies
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, 'latin1'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([len, body, crc]);
+}
+
+function encodePng(width, height, rgb) {
+  const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;   // bit depth
+  ihdr[9] = 2;   // colour type: truecolour
+  const raw = Buffer.alloc(height * (1 + width * 3));
+  for (let y = 0; y < height; y++) {
+    const rowStart = y * (1 + width * 3);
+    raw[rowStart] = 0; // filter: none
+    rgb.copy(raw, rowStart + 1, y * width * 3, (y + 1) * width * 3);
+  }
+  return Buffer.concat([sig, chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
+
+const mix = (a, b, t) => [0, 1, 2].map((i) => Math.round(a[i] + (b[i] - a[i]) * t));
+
+function hsl(h, s, l) {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  const [r, g, b] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255)];
+}
+
+/**
+ * The Lens icon: a dark panel with a stack of step bars, the current one lit. It is what the Lens
+ * actually is, and it stays legible at the small size a Lens icon is shown at. The accent hue comes
+ * from the name, so two procedures never look identical in a list.
+ */
+export function makeLensIcon(lensName, outPath, size = 320) {
+  const hash = crypto.createHash('sha256').update(String(lensName)).digest();
+  const hue = (hash[0] / 255) * 360;
+  const accent = hsl(hue, 0.72, 0.58);
+  const accentDim = hsl(hue, 0.38, 0.32);
+  const bgTop = [16, 22, 30];
+  const bgBottom = [8, 11, 16];
+  const panel = [26, 34, 45];
+
+  const px = Buffer.alloc(size * size * 3);
+  const put = (x, y, c) => { const o = (y * size + x) * 3; px[o] = c[0]; px[o + 1] = c[1]; px[o + 2] = c[2]; };
+
+  // rounded-rect membership with a soft edge, so nothing looks jagged at icon size
+  const inRounded = (x, y, rx, ry, rw, rh, r) => {
+    const cx = Math.min(Math.max(x, rx + r), rx + rw - r);
+    const cy = Math.min(Math.max(y, ry + r), ry + rh - r);
+    const d = Math.hypot(x - cx, y - cy);
+    if (x < rx || x > rx + rw || y < ry || y > ry + rh) return 0;
+    return d <= r - 0.5 ? 1 : d >= r + 0.5 ? 0 : r + 0.5 - d;
+  };
+
+  const s = size / 320;
+  const panelX = 44 * s, panelY = 60 * s, panelW = 232 * s, panelH = 200 * s, panelR = 26 * s;
+  const barX = 70 * s, barR = 7 * s, barH = 14 * s;
+  const bars = [
+    { y: 96 * s, w: 180 * s, on: true },
+    { y: 136 * s, w: 144 * s, on: false },
+    { y: 176 * s, w: 162 * s, on: false },
+    { y: 216 * s, w: 110 * s, on: false },
+  ];
+
+  for (let y = 0; y < size; y++) {
+    const ground = mix(bgTop, bgBottom, y / (size - 1));
+    for (let x = 0; x < size; x++) {
+      let c = ground;
+      const inPanel = inRounded(x, y, panelX, panelY, panelW, panelH, panelR);
+      if (inPanel > 0) c = mix(c, panel, inPanel);
+      for (const b of bars) {
+        const a = inRounded(x, y, barX, b.y, b.w, barH, barR);
+        if (a > 0) c = mix(c, b.on ? accent : accentDim, a);
+      }
+      put(x, y, c);
+    }
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, encodePng(size, size, px));
+  return { path: outPath, size, accent: `#${accent.map((v) => v.toString(16).padStart(2, '0')).join('')}` };
+}
+
+// ---------------------------------------------------------------- applied inside Lens Studio
+const SET_METADATA = `const E: any = (globalThis as any).Editor;
+const a: any = args;
+const FileSystem: any = await import("LensStudio:FileSystem");
+const model: any = pluginSystem.findInterface(E.Model.IModel);
+const project: any = model.project;
+const before = String(project.metaInfo.lensName || "");
+if (!E.Model.MetaInfo.isLensNameValid(String(a.lensName))) {
+  return { error: "Lens Studio rejected the Lens name: " + a.lensName };
+}
+let meta: any = project.metaInfo;
+meta.lensName = String(a.lensName);
+project.metaInfo = meta;
+if (a.iconPath) {
+  const src = new E.Path(String(a.iconPath));
+  if (!FileSystem.exists(src)) return { error: "Lens icon not found: " + a.iconPath };
+  meta = project.metaInfo;
+  meta.setIcon(src);
+  project.metaInfo = meta;
+}
+if (a.signingKeyPath) {
+  const key = new E.Path(String(a.signingKeyPath));
+  if (!FileSystem.exists(key)) return { error: "Signing key not found: " + a.signingKeyPath };
+  meta = project.metaInfo;
+  meta.spkProductionKeyPath = key;
+  project.metaInfo = meta;
+}
+project.save();
+const keyOut = project.metaInfo.spkProductionKeyPath;
+return {
+  before,
+  lensName: String(project.metaInfo.lensName || ""),
+  iconSet: !!project.metaInfo.isIconSet,
+  iconPath: String(project.metaInfo.iconPath || ""),
+  signingKeyPath: keyOut && !keyOut.isEmpty ? keyOut.toString() : "",
+};`;
+
+/**
+ * The production signing key Snap's SPK export needs: an ed25519 private key as pkcs8 PEM, which is
+ * the exact shape Snap's own signing-key.js writes. Node's crypto makes it; no account, no network.
+ * Reused when one is already on disk, so rebuilding a Lens keeps its identity.
+ */
+export function ensureSigningKey(projectDir) {
+  const keyPath = path.join(projectDir, 'specs_signing_key.pem');
+  if (fs.existsSync(keyPath) && /BEGIN PRIVATE KEY/.test(fs.readFileSync(keyPath, 'utf8'))) {
+    return { path: keyPath, created: false };
+  }
+  const { privateKey } = crypto.generateKeyPairSync('ed25519');
+  fs.writeFileSync(keyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+  try { fs.chmodSync(keyPath, 0o600); } catch { /* windows */ }
+  return { path: keyPath, created: true };
+}
+
+/**
+ * Give the freshly built project the Lens name, icon and signing key Snap asks for.
+ * Returns what was set, so the verifier can check it rather than assume it.
+ */
+export async function prepareSubmission(bridge, { projectDir, procedureName, lensName }) {
+  const name = snapLensName(procedureName, lensName);
+  const icon = makeLensIcon(name, path.join(projectDir, 'Cache', 'parley-lens-icon.png'));
+  const key = ensureSigningKey(projectDir);
+  const fwd = (p) => p.split(path.sep).join('/');
+  const applied = await bridge.eec(SET_METADATA, { lensName: name, iconPath: fwd(icon.path), signingKeyPath: fwd(key.path) }, 90000);
+  if (applied?.error) throw new Error(applied.error);
+  return {
+    lensName: applied.lensName,
+    inheritedName: applied.before,
+    nameWasTemplateDefault: /^SpecsBaseTemplate$/i.test(applied.before || ''),
+    iconPath: applied.iconPath,
+    iconAccent: icon.accent,
+    signingKeyPath: applied.signingKeyPath,
+    signingKeyCreated: key.created,
+  };
+}
+
+/** Read back what Snap would see, including whether Lens Studio is signed in. */
+export function readSubmissionState(bridge) {
+  return bridge.eec(`const E: any = (globalThis as any).Editor;
+const model: any = pluginSystem.findInterface(E.Model.IModel);
+const project: any = model.project;
+const FileSystem: any = await import("LensStudio:FileSystem");
+let signedIn: any = null;
+try {
+  const auth: any = pluginSystem.findInterface(E.IAuthorization.interfaceId);
+  signedIn = !E.isNull(auth) && !!auth.isAuthorized;
+} catch (e) { signedIn = null; }
+const name = String(project.metaInfo.lensName || "");
+const icon = String(project.metaInfo.iconPath || "");
+const key = project.metaInfo.spkProductionKeyPath;
+return {
+  lensName: name,
+  lensNameValid: !!name && E.Model.MetaInfo.isLensNameValid(name) && name.toLowerCase() !== "untitled" && name !== "SpecsBaseTemplate",
+  iconPath: icon,
+  iconPresent: !!project.metaInfo.isIconSet && !!icon && FileSystem.exists(new E.Path(icon)),
+  productionKeySet: !!key && !key.isEmpty && FileSystem.exists(key),
+  signedIn,
+};`, {}, 60000);
+}

package/lens-builder/publish.mjs

@@ -0,0 +1,127 @@
+// Takes a built Lens as far towards Snap as this computer can: Snap's own preflight, then Snap's own
+// production SnapOS Package (SPK) export. Both run from lens-builder/vendor/specs-publish, which is
+// Snap's Apache-2.0 toolchain copied unmodified; see that folder's NOTICE.
+//
+// The wall is Lens Studio's own sign-in. Snap's preflight refuses without it and their exporter checks
+// Editor.IAuthorization.isAuthorized directly, so no Lens can be packaged for Snap by anyone, through
+// Parley or by hand, until someone signs in to Lens Studio. Everything on this side of that line
+// (a Lens name Snap accepts, the icon, the production signing key) is done at build time.
+//
+// Registering and submitting the release is deliberately not automated: it is irreversible and needs
+// choices only the owner can make (organisation, category, content rating).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Bridge, DATA } from './lib/bridge.mjs';
+import { readSubmissionState } from './lib/submission.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SNAP_SCRIPTS = path.join(HERE, 'vendor', 'specs-publish', 'scripts');
+const fwd = (p) => p.split(path.sep).join('/');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** The .esproj for a lens id, a run folder name, or an explicit path. */
+export function resolveProject(target) {
+  if (!target) return null;
+  if (/\.esproj$/i.test(target) && fs.existsSync(target)) return path.resolve(target);
+  const asRun = path.join(DATA, 'runs', target, 'metrics.json');
+  const lensId = fs.existsSync(asRun) ? JSON.parse(fs.readFileSync(asRun, 'utf8')).lens_id : target;
+  const dir = path.join(DATA, 'lens-projects', lensId);
+  const esproj = path.join(dir, `${lensId}.esproj`);
+  return fs.existsSync(esproj) ? esproj : null;
+}
+
+async function openProject(bridge, esproj) {
+  const current = await bridge.projectInfo().catch(() => null);
+  if (current && fwd(current.file).toLowerCase() === fwd(esproj).toLowerCase()) return current;
+  await bridge.eec(`const E: any = (globalThis as any).Editor; const model: any = pluginSystem.findInterface(E.Model.IModel);
+model.openProject(new E.Path(String((args as any).file))); return "opening";`, { file: fwd(esproj) });
+  for (let i = 0; i < 30; i++) {
+    await sleep(2000);
+    const info = await bridge.projectInfo().catch(() => null);
+    if (info && fwd(info.file).toLowerCase() === fwd(esproj).toLowerCase()) { await sleep(2000); return info; }
+  }
+  throw new Error(`Timed out opening ${esproj}`);
+}
+
+const SIGN_IN_HELP = 'Sign in to Lens Studio: My Lenses > Login, in the Lens Studio menu bar. That is Snap\'s gate. Until someone signs in, no Lens can be packaged or submitted for Snap by any route, and Parley cannot do it for you.';
+
+/**
+ * @param target  lens id, run folder name, or a path to a .esproj. Omit to use whatever is open.
+ * @returns { stage, ok, signedIn, ready, spkPath, checksum, issues[], next[] }
+ */
+export async function publish(target, { log = () => {} } = {}) {
+  const out = { stage: 'preflight', ok: false, signedIn: null, ready: false, spkPath: null, checksum: null, issues: [], next: [] };
+  const bridge = new Bridge();
+  await bridge.connect();
+
+  const esproj = resolveProject(target);
+  if (target && !esproj) throw new Error(`No built Lens found for "${target}". Run parley lens metrics to see what is on this computer.`);
+  if (esproj) { log(`opening ${path.basename(esproj)}`); await openProject(bridge, esproj); }
+  const info = await bridge.projectInfo();
+  out.project = info.file;
+
+  // What Parley set at build time, read back from the project rather than assumed.
+  const state = await readSubmissionState(bridge).catch(() => null);
+  if (state) {
+    out.signedIn = state.signedIn;
+    out.lensName = state.lensName;
+    out.readyLocally = !!(state.lensNameValid && state.iconPresent && state.productionKeySet);
+    if (!state.lensNameValid) out.issues.push(`The Lens name "${state.lensName}" is not one Snap accepts. Rebuild the Lens so Parley sets it.`);
+    if (!state.iconPresent) out.issues.push('No Lens icon on the project. Rebuild the Lens so Parley sets it.');
+    if (!state.productionKeySet) out.issues.push('No production signing key on the project. Rebuild the Lens so Parley attaches one.');
+  }
+
+  // Snap's own preflight. It returns immediately on auth, so its verdict on the rest is only
+  // visible once signed in; Parley checks name, icon and key itself above regardless.
+  log('running Snap\'s preflight');
+  const pre = await bridge.eecPath(path.join(SNAP_SCRIPTS, 'preflight.ts'), {}, 120000).catch((e) => ({ status: 'FAILED', reason: 'preflight_error', message: e.message }));
+  out.preflight = pre;
+
+  if (pre?.status === 'ACTION_REQUIRED' && pre.reason === 'not_signed_in') {
+    out.stage = 'blocked_on_sign_in';
+    out.signedIn = false;
+    out.next = [SIGN_IN_HELP, 'Then run this command again. Nothing else is missing on this computer.'];
+    return out;
+  }
+  if (pre?.status === 'ACTION_REQUIRED') {
+    out.stage = 'action_required';
+    out.issues.push(...(pre.issues?.map((i) => i.message) ?? [pre.message]).filter(Boolean));
+    out.next = ['Snap needs these before the Lens can be packaged. Fix them in Lens Studio, then run this again.'];
+    return out;
+  }
+  if (pre?.status !== 'READY') {
+    out.stage = 'preflight_failed';
+    out.issues.push(pre?.message || 'Snap\'s preflight did not return READY.');
+    return out;
+  }
+
+  out.ready = true;
+  out.signedIn = true;
+  out.packageId = pre.packageId;
+
+  // Snap's own exporter. Produces <project>/.export/<name>.spk, signed with the production key.
+  log('exporting the SnapOS Package');
+  out.stage = 'package';
+  const pkg = await bridge.eecPath(path.join(SNAP_SCRIPTS, 'package.ts'), {}, 300000);
+  out.package = pkg;
+  if (pkg?.status && pkg.status !== 'PACKAGED' && pkg.status !== 'READY') {
+    out.issues.push(pkg.message || 'The SnapOS Package export did not complete.');
+    return out;
+  }
+  out.spkPath = pkg?.spkPath || pkg?.packagePath || null;
+  out.checksum = pkg?.spkChecksum || pkg?.checksum || null;
+  out.bytes = pkg?.packageBytes ?? (out.spkPath && fs.existsSync(out.spkPath) ? fs.statSync(out.spkPath).size : null);
+  out.ok = !!out.spkPath;
+  out.stage = out.ok ? 'packaged' : 'package_failed';
+  out.next = out.ok
+    ? ['Register and submit the release from Lens Studio, or with Snap\'s authorized-request script. That step is irreversible and needs your organisation, category and content rating, so Parley stops here.']
+    : ['The export did not produce a package. Read the message above.'];
+  return out;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(HERE, 'publish.mjs')) {
+  const r = await publish(process.argv[2], { log: (m) => console.log('  ' + m) });
+  console.log(JSON.stringify(r, null, 2));
+  process.exitCode = r.ok ? 0 : r.stage === 'blocked_on_sign_in' ? 3 : 1;
+}