parley-live 0.5.0 → 0.6.0

package/lens-builder/lenses.mjs

@@ -0,0 +1,113 @@
+// The Lenses a person has made, and getting back to one.
+//
+// A build used to end with the files somewhere only the pipeline knew about. These two calls are what
+// make a finished Lens something the person owns: a list they can see, and a way back into Lens Studio.
+import fs from 'node:fs';
+import path from 'node:path';
+import { Bridge, DATA, PROJECTS } from './lib/bridge.mjs';
+
+/** Every Lens on this computer, newest first, with where it lives and how its last build went. */
+export function listLenses() {
+  if (!fs.existsSync(PROJECTS)) return [];
+  const runs = readRuns();
+  return fs.readdirSync(PROJECTS, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name !== '_templates')
+    .map((d) => {
+      const dir = path.join(PROJECTS, d.name);
+      const esproj = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.esproj'));
+      if (!esproj) return null;
+      const run = runs.find((r) => sameName(r.title, d.name) || sameName(r.lens_id, d.name)) ?? null;
+      return {
+        name: run?.title || d.name,
+        folder: d.name,
+        dir,
+        file: path.join(dir, esproj),
+        builtAt: run?.finished_at ?? fs.statSync(path.join(dir, esproj)).mtime.toISOString(),
+        steps: run?.steps ?? null,
+        passed: run?.pass ?? null,
+        reportPath: run?.reportPath ?? null,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.builtAt).localeCompare(String(a.builtAt)));
+}
+
+/**
+ * Put a Lens back in front of the person.
+ *   where 'lens_studio' (default) opens it in Lens Studio, which is where Send to Spectacles lives.
+ *   where 'folder' only resolves the path; revealing a folder belongs to the app, not to this process.
+ */
+export async function openLens(target, where = 'lens_studio', log = () => {}) {
+  const { resolveProject, openProject } = await import('./publish.mjs');
+  const file = resolveProject(target || '');
+  if (!file) {
+    const known = listLenses().map((l) => l.name);
+    throw new Error(`No Lens called "${target}" on this computer.${known.length ? ` Built so far: ${known.join(', ')}.` : ' Nothing has been built yet.'}`);
+  }
+  const dir = path.dirname(file);
+  if (where === 'folder') return { file, dir, opened: 'folder' };
+  log(`opening ${path.basename(file)} in Lens Studio`);
+  const bridge = new Bridge();
+  await bridge.connect();
+  await openProject(bridge, file);
+  return { file, dir, opened: 'lens_studio' };
+}
+
+function readRuns() {
+  const runsDir = path.join(DATA, 'runs');
+  if (!fs.existsSync(runsDir)) return [];
+  return fs.readdirSync(runsDir)
+    .map((name) => {
+      const metrics = path.join(runsDir, name, 'metrics.json');
+      if (!fs.existsSync(metrics)) return null;
+      try {
+        const m = JSON.parse(fs.readFileSync(metrics, 'utf8'));
+        return { ...m, reportPath: path.join(runsDir, name, 'report.md') };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.finished_at).localeCompare(String(a.finished_at)));
+}
+
+const sameName = (a, b) => String(a ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '') === String(b ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+
+/**
+ * Put a Lens on the paired Spectacles: the "Send to Spectacles" step, done by Parley.
+ *
+ * Snap exposes it over MCP as push_leaf_lens, which pushes whatever project is open, so the Lens is
+ * opened first. The execution target has to be switched to the device or the push goes to the
+ * preview and reports success, which would be a lie. On failure the target is put back, so Lens
+ * Studio is left the way it was found.
+ */
+export async function sendToGlasses(target, log = () => {}) {
+  const { resolveProject, openProject } = await import('./publish.mjs');
+  const file = resolveProject(target || '');
+  if (!file) throw new Error(`No Lens called "${target}" on this computer.`);
+  // Nobody should sit and watch a spinner for four minutes to learn their glasses are not on.
+  const bridge = new Bridge({ timeoutMs: 90000 });
+  await bridge.connect();
+  log('opening the Lens in Lens Studio');
+  await openProject(bridge, file);
+  await bridge.call('open_leaf_panel', {});
+  log('pointing Lens Studio at your Spectacles');
+  const aimed = await bridge.call('set_leaf_execution_target', { onDevice: true });
+  if (!aimed || aimed.target !== 'device') {
+    await bridge.call('set_leaf_execution_target', { onDevice: false }).catch(() => {});
+    throw new Error('Lens Studio would not switch to the glasses. Pair your Spectacles in Lens Studio first.');
+  }
+  log('sending it across');
+  try {
+    const pushed = await bridge.call('push_leaf_lens', {});
+    if (!pushed || pushed.pushed !== true || pushed.target !== 'device') {
+      throw new Error(`The Lens went to the ${pushed && pushed.target ? pushed.target : 'preview'} instead of the glasses.`);
+    }
+    return { file, dir: path.dirname(file), sent: true, target: 'device' };
+  } catch (e) {
+    await bridge.call('set_leaf_execution_target', { onDevice: false }).catch(() => {});
+    // Snap's message for "nothing answered" is about a lens not starting; say what it means.
+    const notThere = /did not start on the device|no device|not paired|timed out|timeout|abort/i.test(e.message);
+    throw new Error(notThere
+      ? 'No Spectacles answered. Put them on and wake them, pair them in Lens Studio, and keep them on the same Wi-Fi as this computer, then ask again.'
+      : e.message);
+  }
+}

package/lens-builder/lib/handoff.mjs

@@ -0,0 +1,88 @@
+// Make the project folder something a person can open without being told which file to click.
+//
+// A Lens Studio project is a developer's folder: Assets, Packages, Cache, Workspaces, and the
+// agent-tooling files Snap's template ships (.clad, .cursor, AGENTS.md and friends). Someone who
+// asked for a training guide opens that and has no idea what any of it is. So after a build the
+// folder is cut down to the two things that mean something to them: the Lens itself, and a note
+// telling them what to do. Everything else is marked hidden. Nothing is deleted or moved, so Lens
+// Studio still finds every file exactly where it expects.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const README = 'Open me first.txt';
+
+/** Hide Lens Studio's working files on Windows. Everywhere else this is a no-op. */
+function hide(dir, names) {
+  if (process.platform !== 'win32' || !names.length) return 0;
+  const sysRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+  const attrib = path.join(sysRoot, 'System32', 'attrib.exe');
+  if (!fs.existsSync(attrib)) return 0;
+  let hidden = 0;
+  for (const name of names) {
+    try { execFileSync(attrib, ['+H', path.join(dir, name)], { stdio: 'pipe', windowsHide: true }); hidden++; }
+    catch { /* a file Lens Studio holds open can refuse; it stays visible, which is not worth failing a build over */ }
+  }
+  return hidden;
+}
+
+function readmeText({ title, esprojName, steps, completionMessage }) {
+  const lines = [
+    title,
+    '='.repeat(title.length),
+    '',
+    'This folder is your Lens: the step-by-step guide Parley built for you.',
+    '',
+    'TO OPEN IT',
+    `  Double-click "${esprojName}". That opens it in Lens Studio.`,
+    '  Or just ask Parley to open it. You do not have to come here at all.',
+    '',
+    'TO PUT IT ON YOUR GLASSES',
+    '  Wake your Spectacles, make sure they are paired in Lens Studio and on',
+    '  the same Wi-Fi as this computer, then ask Parley to send it to your',
+    '  glasses. It does the rest.',
+    '  By hand instead: open it in Lens Studio and press "Send to Spectacles".',
+    '',
+    'TO CHANGE IT',
+    '  Tell Parley what to change, in your own words. It rebuilds the whole',
+    '  Lens and tests it again. You do not edit anything in here by hand.',
+    '',
+    `WHAT IT GUIDES (${steps.length} step${steps.length === 1 ? '' : 's'})`,
+    ...steps.map((s, i) => `  ${i + 1}. ${s.instruction}${s.warning ? `\r\n     Caution: ${s.warning}` : ''}`),
+  ];
+  if (completionMessage) lines.push('', `AT THE END, THE WEARER SEES`, `  ${completionMessage}`);
+  lines.push(
+    '',
+    'THE REST OF THIS FOLDER',
+    '  Lens Studio keeps its own working files here. They are hidden because',
+    '  you never need to touch them. Do not move or rename anything: the Lens',
+    '  stops opening if you do.',
+    '',
+    `Built by Parley on ${new Date().toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })}.`,
+    '',
+  );
+  return lines.join('\r\n');
+}
+
+/**
+ * Leave the project folder in a state a non-developer can use.
+ * Returns what it did, so the build report and the app can say so.
+ */
+export function tidyProjectFolder(projectDir, { title, esproj, steps = [], completionMessage = '' } = {}) {
+  const out = { readme: null, hidden: 0, esproj: esproj ? path.basename(esproj) : null };
+  if (!projectDir || !fs.existsSync(projectDir)) return out;
+  const esprojName = out.esproj || fs.readdirSync(projectDir).find((f) => f.toLowerCase().endsWith('.esproj')) || '';
+  out.esproj = esprojName || null;
+
+  const readmePath = path.join(projectDir, README);
+  try {
+    fs.writeFileSync(readmePath, readmeText({ title: title || esprojName.replace(/\.esproj$/i, ''), esprojName, steps, completionMessage }), 'utf8');
+    out.readme = readmePath;
+  } catch { /* a read-only folder is not a reason to fail a build that otherwise passed */ }
+
+  // Everything except the Lens and the note. Lens Studio reads hidden files exactly as before.
+  const keep = new Set([esprojName.toLowerCase(), README.toLowerCase()]);
+  const clutter = fs.readdirSync(projectDir).filter((n) => !keep.has(n.toLowerCase()));
+  out.hidden = hide(projectDir, clutter);
+  return out;
+}

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,145 @@
+// 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, PROJECTS } 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. */
+/**
+ * A Lens can be asked for by its id, by the folder the person sees in Documents, or by the name they
+ * gave the procedure. All three have to find it, because the name in chat is rarely the id.
+ */
+function findProjectDir(lensId) {
+  if (!fs.existsSync(PROJECTS)) return null;
+  // Never hand back the caller's spelling: Windows matches paths case-insensitively, so "espresso
+  // machine" would resolve and then be shown to the person instead of the folder they actually have.
+  const dirs = fs.readdirSync(PROJECTS, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== '_templates');
+  const exact = dirs.find((d) => d.name === lensId);
+  if (exact) return path.join(PROJECTS, exact.name);
+  const want = String(lensId).toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const hit = dirs.find((d) => d.name.toLowerCase().replace(/[^a-z0-9]+/g, '') === want)
+    || dirs.find((d) => d.name.toLowerCase().replace(/[^a-z0-9]+/g, '').includes(want) && want.length > 3);
+  return hit ? path.join(PROJECTS, hit.name) : null;
+}
+
+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 = findProjectDir(lensId);
+  if (!dir) return null;
+  const esproj = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.esproj'));
+  return esproj ? path.join(dir, esproj) : null;
+}
+
+export 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;
+}