parley-live 0.4.2 → 0.5.1

package/README.md

@@ -20,6 +20,7 @@ parley ugc-ad --product product.jpg --name "Cold Brew Kit" --actor jordan --mark
 | `parley voice "<text>" \| --file script.txt` | Narration as a hosted WAV. `--voice warm\|energetic\|documentary\|deep\|bright\|storyteller`, `--quality natural\|fish\|studio`, `--no-fallback`, `--out`. Natural voice: 1 credit per 1,000 characters; studio: 1 per 300. Becomes `@last` for `--narration`. `parley voices` lists personas and prices. |
 | `parley studio …` | The film pipeline without JSON: `character add\|cast\|list`, `location add\|cast\|list`, `shot add\|list`, `render <shotId> [--wait]`, `assemble`, `reels`. Every subcommand takes `--project proj_…`. |
 | `parley deploy <dir> --name <slug>` | Ship a built static site (index.html at the root) to a live URL. Reuse `--project proj_…` to redeploy the same site at the same URL. Free. |
+| `parley lens <status|connect|build|describe|record|metrics>` | A Snap Specs Lens from a work procedure, built and tested on this computer through Lens Studio: a hands-free step-by-step guide with pinch buttons and optional voice shortcuts. `status` says exactly what to set up; `build <form.json>` is free; `describe "..."` plans the steps from prose (about a cent, billed to your credits). Every build is checked in the Lens Studio preview; what only glasses can judge is marked, never passed. |
 | `parley login [--no-browser]` | Device-code sign-in. Prints a link, you sign in once in the browser, the CLI receives a session token. `--no-browser` prints the link instead of opening it (cloud sandboxes, SSH). |
 | `parley account` | Credit balance. |
 | `parley engines` | Which video engines this server can run right now, with credit rates. |

package/dist/index.js

@@ -17,7 +17,8 @@
 import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, loadLast, openInBrowser, rememberLast, resolveRef, saveCredentials, sleep, } from './client.js';
-const VERSION = '0.4.2';
+import { cmdLens, LensError } from './lens.js';
+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) {
@@ -1004,6 +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|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]);
@@ -1077,6 +1079,10 @@ async function main(argv) {
             case 'deploy':
                 await cmdDeploy(p);
                 break;
+            case 'lens':
+            case 'specs':
+                await cmdLens(p.positionals, p.flags, JSON_MODE);
+                break;
             case 'help':
             case '--help':
             case '-h':
@@ -1088,7 +1094,7 @@ async function main(argv) {
         return 0;
     }
     catch (e) {
-        const code = e instanceof CliError ? e.exitCode : 1;
+        const code = e instanceof CliError || e instanceof LensError ? e.exitCode : 1;
         const message = humanizeServerMessage(e?.message || String(e));
         if (JSON_MODE)
             console.log(JSON.stringify({ ok: false, error: message, code }));

package/dist/lens.js

@@ -0,0 +1,252 @@
+/**
+ * `parley lens`: build a Snap Specs Lens from a plain-language procedure or a form, on this computer, through
+ * Lens Studio. The pipeline (lens-builder/) ships inside this package; it talks only to Lens Studio's local MCP
+ * server on 127.0.0.1, and its planning step goes through Parley's proxy on the signed-in account.
+ *
+ *   parley lens status                      Lens Studio running? connected? build tools present?
+ *   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
+ */
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { backendUrl, currentToken, homeDir } from './client.js';
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BUILDER = path.join(PKG_ROOT, 'lens-builder');
+export class LensError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+const str = (v) => (typeof v === 'string' ? v : Array.isArray(v) ? v[0] : undefined);
+function mcpConfigPath() { return path.join(homeDir(), 'lens-studio-mcp.json'); }
+/** Accepts the JSON Lens Studio copies to the clipboard, or a bare { url, token }. Loopback only. */
+export function parseMcpConfig(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LensError('That does not look like the config Lens Studio copies. In Lens Studio: AI Assistant > AI Model Context Protocol (MCP) > Configure Server > Copy MCP Config, then pass it with --config.', 65);
+    }
+    const server = parsed?.mcpServers ? Object.values(parsed.mcpServers)[0] : parsed;
+    const url = server?.url;
+    const auth = server?.headers?.Authorization ?? (server?.token ? `Bearer ${server.token}` : undefined);
+    if (!url || !auth)
+        throw new LensError('The config is missing the server address or the connection code.', 65);
+    const host = new URL(url).hostname;
+    if (host !== 'localhost' && host !== '127.0.0.1')
+        throw new LensError('Only a Lens Studio running on this computer can be connected.', 65);
+    return { url, token: auth.replace(/^Bearer\s+/i, '') };
+}
+function loadMcpConfig() {
+    try {
+        return existsSync(mcpConfigPath()) ? JSON.parse(readFileSync(mcpConfigPath(), 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function dataDir() { return process.env.PARLEY_LENS_DATA_DIR || path.join(homeDir(), 'lens-builder'); }
+function runPipeline(command, input, onEvent) {
+    if (!existsSync(path.join(BUILDER, 'cli.mjs')))
+        throw new LensError('This install of parley-live is missing the Lens Builder. Reinstall: npm install -g parley-live@latest', 70);
+    const cfg = loadMcpConfig();
+    const env = { ...process.env, PARLEY_LENS_DATA_DIR: dataDir(), PARLEY_REQUIRE_PROXY: '1' };
+    if (cfg) {
+        env.LENS_MCP_URL = cfg.url;
+        env.LENS_MCP_TOKEN = cfg.token;
+    }
+    const token = currentToken();
+    if (token) {
+        env.PARLEY_PROXY_URL = backendUrl();
+        env.PARLEY_PROXY_TOKEN = token;
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [path.join(BUILDER, 'cli.mjs'), command], { env, cwd: PKG_ROOT, windowsHide: true });
+        const events = [];
+        let buffer = '', stderr = '';
+        child.stdout.on('data', (c) => {
+            buffer += c.toString('utf8');
+            let nl;
+            while ((nl = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, nl).trim();
+                buffer = buffer.slice(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    const e = JSON.parse(line);
+                    events.push(e);
+                    onEvent?.(e);
+                }
+                catch { /* not an event */ }
+            }
+        });
+        child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
+        child.on('error', reject);
+        child.on('close', () => events.length ? resolve(events) : reject(new LensError(stderr.trim().slice(0, 500) || 'The Lens Builder produced no output.', 70)));
+        child.stdin.end(input === undefined ? '' : JSON.stringify(input));
+    });
+}
+/** What a person must do next, in order. Empty when everything is ready. */
+export function nextSteps(s) {
+    const steps = [];
+    if (!s.configured) {
+        steps.push('Install Lens Studio 5.22 or later from https://ar.snap.com/download and open it. Create a project (Home > SPECS > Base Template) and leave it open; the MCP server starts with a project open.');
+        steps.push('In Lens Studio: AI Assistant > AI Model Context Protocol (MCP) > Configure Server > Copy MCP Config. Then run: parley lens connect --config \'<paste>\'. One time only: Lens Studio keeps the same code in your keychain across restarts.');
+    }
+    else if (!s.reachable) {
+        steps.push(/rejected/i.test(s.error || '') ? 'Lens Studio rejected the saved connection code. Copy a fresh one (AI Assistant > MCP > Configure Server > Copy MCP Config) and run parley lens connect --config again.' : 'Start Lens Studio and open any project (Home > SPECS > Base Template), then run parley lens status again.');
+    }
+    else if (!s.toolsOk) {
+        steps.push(`Lens Studio is missing the build tools (${(s.missingTools || []).join(', ')}). Lens Studio installs Snap's "Core Chat Tools" and "Run Editor Code" packages by itself after a restart while online; if they are still missing, open Window > Asset Library in Lens Studio and install them, then restart Lens Studio.`);
+    }
+    return steps;
+}
+export async function cmdLens(positionals, flags, jsonMode) {
+    const sub = positionals[0];
+    const out = (o, human) => { if (jsonMode)
+        console.log(JSON.stringify(o));
+    else
+        human(); };
+    if (sub === 'connect') {
+        const raw = str(flags.config) ?? (flags.config === undefined && positionals[1] ? positionals[1] : undefined);
+        if (!raw)
+            throw new LensError('Usage: parley lens connect --config \'<the JSON Lens Studio copied>\'\n  In Lens Studio: AI Assistant > AI Model Context Protocol (MCP) > Configure Server > Copy MCP Config.', 64);
+        const cfg = parseMcpConfig(raw.startsWith('@') ? readFileSync(raw.slice(1), 'utf8') : raw);
+        mkdirSync(homeDir(), { recursive: true });
+        writeFileSync(mcpConfigPath(), JSON.stringify(cfg) + '\n', { mode: 0o600 });
+        try {
+            chmodSync(mcpConfigPath(), 0o600);
+        }
+        catch { /* windows */ }
+        const [s] = await runPipeline('status', undefined);
+        const steps = nextSteps(s);
+        out({ ok: s.reachable && s.toolsOk, saved: mcpConfigPath(), status: s, nextSteps: steps }, () => {
+            console.log(`Saved the connection to ${mcpConfigPath()} (this file only; never share it).`);
+            console.log(s.reachable && s.toolsOk ? 'Connected to Lens Studio. Build tools present. Ready to build.' : `Saved, but not ready yet:\n  - ${steps.join('\n  - ')}`);
+        });
+        return;
+    }
+    if (sub === 'status' || sub === undefined) {
+        const [s] = await runPipeline('status', undefined);
+        const steps = nextSteps(s);
+        out({ ok: !!(s.reachable && s.toolsOk), ...s, signedIn: !!currentToken(), nextSteps: steps }, () => {
+            console.log(`Lens Studio: ${s.reachable ? 'connected' : s.configured ? 'not answering' : 'not connected yet'}`);
+            console.log(`Build tools: ${s.toolsOk ? 'present' : 'missing'}`);
+            console.log(`Parley sign-in (needed only for "describe"): ${currentToken() ? 'yes' : 'no, run parley login'}`);
+            if (s.project?.file)
+                console.log(`Open project: ${s.project.file}`);
+            if (steps.length)
+                console.log(`\nNext:\n  - ${steps.join('\n  - ')}`);
+            else
+                console.log('\nReady. Try: parley lens build <form.json>   or   parley lens describe "<your procedure>"');
+        });
+        if (!(s.reachable && s.toolsOk))
+            throw new LensError(steps[0] || s.error || 'Lens Studio is not ready.', 3);
+        return;
+    }
+    if (sub === 'build' || sub === 'describe') {
+        let form, planner = null;
+        if (sub === 'build') {
+            const file = positionals[1];
+            if (!file)
+                throw new LensError('Usage: parley lens build <form.json>\n  {"procedureName":"...","steps":[{"instruction":"...","warning":""}],"completionMessage":"...","voiceShortcuts":true}', 64);
+            form = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        else {
+            const prompt = positionals.slice(1).join(' ').trim();
+            if (!prompt)
+                throw new LensError('Usage: parley lens describe "<the procedure, in your own words>"', 64);
+            if (!currentToken())
+                throw new LensError('Describing a Lens uses a Parley model call. Run parley login first, or write the steps yourself and use parley lens build.', 2);
+            const [p] = await runPipeline('plan', { prompt });
+            if (p.type === 'error')
+                throw new LensError(p.error, /credits/i.test(p.error) ? 4 : 1);
+            if (p.decision !== 'build') {
+                out({ ok: false, decision: p.decision, question: p.question, reason: p.reason, costUsd: p.costUsd }, () => console.log(p.decision === 'clarify' ? `One question first: ${p.question}` : `This cannot be built as asked: ${p.reason}`));
+                throw new LensError(p.decision === 'clarify' ? 'Answer the question and describe it again.' : 'Nothing was built.', 5);
+            }
+            planner = { ...p, prompt };
+            form = p.form;
+            if (!jsonMode) {
+                console.log(`Planned "${form.procedureName}", ${form.steps.length} step(s), model cost USD ${p.costUsd} (billed to your Parley credits). Building...`);
+            }
+            if (flags['plan-only']) {
+                out({ ok: true, form, costUsd: p.costUsd }, () => console.log(JSON.stringify(form, null, 2)));
+                return;
+            }
+        }
+        const events = await runPipeline('build', { form, planner }, (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({ ok: r.ok, lens_id: r.lens_id, iterations: r.iterations, seconds: r.seconds, costUsd: r.costUsd, runDir: r.runDir, reportPath: r.reportPath, checks: r.checks }, () => {
+            console.log(r.ok ? `\nPASS: ${r.lens_id} passed every preview check in ${r.seconds}s.` : `\nFAIL: ${r.lens_id} needs a person to look at it.`);
+            for (const c of r.checks || [])
+                console.log(`  ${c.status === 'pass' ? 'PASS' : c.status === 'fail' ? 'FAIL' : 'ON GLASSES'}  ${c.item}`);
+            console.log(`Report: ${r.reportPath}\nNext: pair your Specs in Lens Studio and press Send to Spectacles; publish from Lens Studio.`);
+        });
+        if (!r.ok)
+            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']);
+        const pub = str(flags.published);
+        if (!run || (!hw && !pub && !str(flags.notes)))
+            throw new LensError('Usage: parley lens record <run-folder-name> [--on-glasses passed|issues] [--published submitted|published] [--notes "..."]', 64);
+        const map = { passed: 'passed on glasses', issues: 'issues found on glasses', untested: 'not tested', submitted: 'submitted', published: 'published', unpublished: 'not published' };
+        const [r] = await runPipeline('record', { run, hardwareTest: hw ? map[hw] || hw : undefined, publishStatus: pub ? map[pub] || pub : undefined, notes: str(flags.notes) });
+        if (r.type === 'error')
+            throw new LensError(r.error, 65);
+        out({ ok: true, ...r }, () => console.log(`Recorded for ${r.title}: on glasses = ${r.hardwareTest}, published = ${r.publishStatus}`));
+        return;
+    }
+    if (sub === 'metrics') {
+        const [m] = await runPipeline('metrics', undefined);
+        out({ ok: true, ...m }, () => { for (const l of m.lenses || [])
+            console.log(`${l.pass ? 'PASS' : 'FAIL'}  ${String(l.seconds).padStart(4)}s  ${l.steps} steps  ${l.hardwareTest}  ${l.publishStatus}  ${l.title}  (${l.run})`); if (!(m.lenses || []).length)
+            console.log('No Lenses built on this computer yet.'); });
+        return;
+    }
+    throw new LensError(`Unknown: parley lens ${sub}. Use status | connect | build | describe | publish | record | metrics.`, 64);
+}