@scribe-platform/cli 0.7.0 → 0.9.0

package/dist/lib/proof-preview.js

@@ -0,0 +1,318 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { basename, resolve, sep } from 'node:path';
+import { ENTRY_PATH, extensionOf, PROOF_CONTENT_TYPES } from './proof-folder.js';
+/**
+ * RFC 0029 — `scribe proof preview`: a Proof folder served the way a Client
+ * will see it, before anything is pushed.
+ *
+ * Same sandbox CSP, same runtime injected the same way, same iframe sandbox
+ * attribute — so a Proof that works here works for the Client, and one that
+ * breaks under the sandbox (a script reading `localStorage`, say) breaks here
+ * first. The panel around it is a stand-in for the real review page: it keeps
+ * hearts, comments and pins in memory so they show up on the page as they
+ * would, and prints each one to the terminal. Nothing is saved anywhere.
+ */
+/** Mirrors the admin's `PROOF_CONTENT_CSP`. No `allow-same-origin`, ever. */
+export const PREVIEW_CSP = 'sandbox allow-scripts allow-forms allow-popups allow-modals';
+const PREFIX = '/c/local/';
+const RUNTIME_PATH = '_scribe/proof.js';
+/**
+ * Must match `PROTOCOL_VERSION` in `@scribe-cms/proof-runtime`'s protocol
+ * module. Not imported from it: the CLI ships to npm and only gets the bundled
+ * script copied in at build time, never the package. A mismatch is loud — the
+ * runtime drops every message and the preview draws no affordances at all.
+ */
+const PROTOCOL_VERSION = 7;
+/**
+ * The runtime bundle, copied in from `@scribe-cms/proof-runtime` at build time
+ * by scripts/bundle-runtime.mjs — the CLI is published to npm and can't depend
+ * on the private workspace package at install time. `../../runtime/` resolves
+ * to the package root from both `src/lib/` (tests) and `dist/lib/` (published).
+ */
+export function loadRuntimeSource() {
+    const file = new URL('../../runtime/proof.js', import.meta.url);
+    if (!existsSync(file)) {
+        throw new Error('The Proof runtime is missing from this install. Reinstall the CLI (or, in the repo, run `npm run build --workspace=@scribe-platform/cli`).');
+    }
+    return readFileSync(file, 'utf8');
+}
+/** Same placement rule as the admin's `injectRuntime`: first thing in `<head>`, src relative to the file's depth. */
+export function injectRuntime(html, path) {
+    const depth = path.split('/').length - 1;
+    const tag = `<script src="${'../'.repeat(depth)}${RUNTIME_PATH}"></script>`;
+    const at = (index) => html.slice(0, index) + tag + html.slice(index);
+    const head = /<head(\s[^>]*)?>/i.exec(html);
+    if (head)
+        return at(head.index + head[0].length);
+    const body = /<body(\s[^>]*)?>/i.exec(html);
+    if (body)
+        return at(body.index);
+    const doctype = /^\s*<!doctype[^>]*>/i.exec(html);
+    if (doctype)
+        return at(doctype[0].length);
+    return tag + html;
+}
+function contentHeaders(contentType) {
+    return {
+        'Content-Type': contentType,
+        'Content-Security-Policy': PREVIEW_CSP,
+        'Referrer-Policy': 'no-referrer',
+        'X-Content-Type-Options': 'nosniff',
+        // Ashley edits and reloads; never serve her a stale copy.
+        'Cache-Control': 'no-store',
+    };
+}
+/**
+ * The file a request path names inside the folder, or null. Hidden files and
+ * anything outside the folder are never served — the same files a push would
+ * leave out.
+ */
+export function resolvePreviewFile(dir, requestPath) {
+    let segments;
+    try {
+        segments = requestPath.split('/').map(decodeURIComponent);
+    }
+    catch {
+        return null;
+    }
+    if (segments.some((s) => s === '' || s === '.' || s === '..' || s.startsWith('.') || s.includes('/') || s.includes('\\')))
+        return null;
+    const root = resolve(dir);
+    const target = resolve(root, ...segments);
+    if (!target.startsWith(root + sep))
+        return null;
+    if (!existsSync(target) || !statSync(target).isFile())
+        return null;
+    return target;
+}
+export async function startPreview(args) {
+    const dir = resolve(args.dir);
+    const log = args.log ?? ((line) => console.log(line));
+    const runtime = args.runtimeSource ?? loadRuntimeSource();
+    const shell = shellPage(basename(dir));
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const send = (status, headers, body) => {
+            res.writeHead(status, headers);
+            res.end(body);
+        };
+        if (req.method === 'POST' && url.pathname === '/__log') {
+            let body = '';
+            req.on('data', (chunk) => (body += chunk));
+            req.on('end', () => {
+                try {
+                    const { line } = JSON.parse(body);
+                    if (typeof line === 'string')
+                        log(line.slice(0, 2000));
+                }
+                catch {
+                    // a malformed log line from our own page; nothing to print
+                }
+                send(204, {});
+            });
+            return;
+        }
+        if (req.method !== 'GET' && req.method !== 'HEAD')
+            return send(405, { 'Content-Type': 'text/plain' }, 'Method not allowed\n');
+        if (url.pathname === '/')
+            return send(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' }, shell);
+        if (url.pathname === '/c/local' || url.pathname === PREFIX)
+            return send(307, { Location: `${PREFIX}${ENTRY_PATH}` });
+        if (!url.pathname.startsWith(PREFIX))
+            return send(404, contentHeaders('text/plain; charset=utf-8'), 'Not found\n');
+        const path = url.pathname.slice(PREFIX.length);
+        if (path === RUNTIME_PATH)
+            return send(200, contentHeaders('text/javascript; charset=utf-8'), runtime);
+        const file = resolvePreviewFile(dir, path);
+        const ext = file ? extensionOf(file) : null;
+        const contentType = ext ? PROOF_CONTENT_TYPES[ext] : undefined;
+        if (!file || !contentType) {
+            // Same 404 for a missing file and a type a push would refuse: either
+            // way the Client would never see it, so neither should the preview.
+            return send(404, contentHeaders('text/plain; charset=utf-8'), `Not in this Proof: ${path}\n`);
+        }
+        const bytes = readFileSync(file);
+        if (contentType.startsWith('text/html')) {
+            return send(200, contentHeaders(contentType), injectRuntime(bytes.toString('utf8'), decodeURIComponent(path)));
+        }
+        return send(200, contentHeaders(contentType), bytes);
+    });
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        // Loopback only: a preview is for the machine it runs on.
+        server.listen(args.port ?? 0, '127.0.0.1', () => resolveListen());
+    });
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => new Promise((done) => server.close(() => done())),
+    };
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+/**
+ * The stand-in review page. Deliberately plain — the real one (plan PR 6) is
+ * branded and built from the admin's design system; this one only has to make
+ * the runtime's behaviour visible and print what a Client's feedback would be.
+ */
+function shellPage(folder) {
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Preview · ${escapeHtml(folder)}</title>
+<style>
+  :root { color-scheme: light dark; --bg: #f8fafc; --panel: #fff; --text: #0f172a; --muted: #64748b; --line: #e2e8f0; --accent: #2563eb; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0b1220; --panel: #111827; --text: #e5e7eb; --muted: #94a3b8; --line: #1f2937; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; height: 100vh; display: grid; grid-template-columns: 1fr 320px; background: var(--bg); color: var(--text);
+    font: 14px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  main { display: grid; place-items: start center; overflow: auto; padding: 16px; }
+  iframe { width: 100%; height: calc(100vh - 32px); border: 1px solid var(--line); border-radius: 8px; background: #fff; transition: width .2s; }
+  iframe.phone { width: 390px; }
+  aside { border-left: 1px solid var(--line); background: var(--panel); display: flex; flex-direction: column; min-height: 0; }
+  header { padding: 16px; border-bottom: 1px solid var(--line); }
+  h1 { margin: 0 0 4px; font-size: 15px; } p { margin: 0; color: var(--muted); font-size: 13px; }
+  .tools { display: flex; flex-wrap: wrap; gap: 8px; padding: 12px 16px; border-bottom: 1px solid var(--line); }
+  button { font: inherit; padding: 6px 12px; border-radius: 6px; border: 1px solid var(--line); background: var(--panel); color: var(--text); cursor: pointer; }
+  button[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: #fff; }
+  ol { list-style: none; margin: 0; padding: 8px 16px; overflow: auto; flex: 1; }
+  li { padding: 8px 0; border-bottom: 1px solid var(--line); font-size: 13px; }
+  li.focus { background: color-mix(in srgb, var(--accent) 12%, transparent); }
+  li .when { color: var(--muted); font-size: 12px; }
+  @media (max-width: 800px) { body { grid-template-columns: 1fr; grid-template-rows: 1fr 40vh; } aside { border-left: 0; border-top: 1px solid var(--line); } }
+</style></head>
+<body>
+<main><iframe id="proof" title="The Proof" src="${PREFIX}${ENTRY_PATH}" sandbox="allow-scripts allow-forms allow-popups allow-modals"></iframe></main>
+<aside>
+  <header><h1>Preview · ${escapeHtml(folder)}</h1><p>What the Client will see: click anywhere on the work to leave a comment. This is a rehearsal — nothing is saved or sent.</p></header>
+  <div class="tools">
+    <button id="phone" type="button" aria-pressed="false">Phone width</button>
+    <button id="reset" type="button">Clear</button>
+  </div>
+  <ol id="log" aria-live="polite"></ol>
+</aside>
+<script>
+  const env = { scribe: 'proof', protocolVersion: ${PROTOCOL_VERSION} };
+  const frame = document.getElementById('proof');
+  const list = document.getElementById('log');
+  const ME = { initials: 'Y', color: '#2563eb' };
+  let state = { options: {}, pins: [] };
+  let seq = 0;
+  let labels = {};
+  let lastUnplaced = '';
+
+  function post(message) { frame.contentWindow.postMessage({ ...env, ...message }, '*'); }
+  function push() { post({ type: 'feedback', feedback: state }); }
+  function option(id) { return state.options[id] || (state.options[id] = { up: 0, down: 0, mine: null, comments: 0, reactions: [] }); }
+  function name(id) { return labels[id] ? labels[id] + ' (' + id + ')' : id; }
+
+  function log(line, id) {
+    const li = document.createElement('li');
+    if (id) li.dataset.pin = id;
+    li.innerHTML = '<div></div><div class="when"></div>';
+    li.firstChild.textContent = line;
+    li.lastChild.textContent = new Date().toLocaleTimeString();
+    list.prepend(li);
+    fetch('/__log', { method: 'POST', body: JSON.stringify({ line }) }).catch(() => {});
+  }
+
+  window.addEventListener('message', (event) => {
+    if (event.source !== frame.contentWindow) return;
+    const m = event.data;
+    if (!m || m.scribe !== 'proof' || m.protocolVersion !== ${PROTOCOL_VERSION}) return;
+    switch (m.type) {
+      case 'ready':
+        labels = Object.fromEntries((m.options || []).map((o) => [o.id, o.label]));
+        post({ type: 'init', mode: 'review', reviewer: { name: 'You (preview)' }, me: ME, canReply: true, feedback: state });
+        log('Loaded ' + m.path + ' — ' + (m.options.length ? m.options.length + ' option(s): ' + m.options.map((o) => o.id).join(', ') : 'no options marked'));
+        break;
+      case 'react': {
+        // One Reaction per person per Option, so a second one rewrites the
+        // first — the same rule the real API enforces.
+        const o = option(m.optionId);
+        const body = (m.body || '').trim();
+        let entry = o.reactions.find((r) => r.mine);
+        if (!entry) {
+          entry = { id: 'r' + (++seq), reaction: m.reaction, author: 'You', body: '', mine: true, when: 'just now', person: ME, replies: [] };
+          o.reactions.push(entry);
+        }
+        if (entry.reaction !== m.reaction) o[entry.reaction]--;
+        entry.reaction = m.reaction;
+        if (body) entry.body = body;
+        o.up = o.reactions.filter((r) => r.reaction === 'up').length;
+        o.down = o.reactions.filter((r) => r.reaction === 'down').length;
+        o.mine = m.reaction;
+        log((m.reaction === 'up' ? '👍 ' : '👎 ') + name(m.optionId) + (body ? ' — ' + body : ''));
+        // The composer in the page is waiting on this whenever words came
+        // with the thumb, exactly as it is for a comment.
+        if (m.body !== null && m.body !== undefined) post({ type: 'comment-result', ok: true, error: null });
+        push();
+        break;
+      }
+      case 'comment': {
+        // The composer lives in the page now, so this one case covers what the
+        // reviewer typed and what the Proof's own script said.
+        const body = (m.body || '').trim();
+        if (m.parentId) {
+          // A reply, so it belongs under the pin it answers rather than on the
+          // page — the same filing the real shell does.
+          // Under a pin, or under one of an Option's Reactions — the real
+          // shell files a reply by its parent, wherever that parent lives.
+          const parent = state.pins.find((p) => p.id === m.parentId) ||
+            Object.values(state.options).flatMap((o) => o.reactions).find((r) => r.id === m.parentId);
+          if (parent) parent.replies.push({ id: m.parentId + '-r' + (parent.replies.length + 1), author: 'You (preview)', body, mine: true, when: 'just now', person: ME });
+          log('↩ Replied: "' + body + '"', m.parentId);
+        } else if (m.pin) {
+          const n = state.pins.length + 1, id = 'pin-' + n;
+          state.pins.push({ id, number: n, anchor: m.pin, mine: true, author: 'You (preview)', body, when: 'just now', person: ME, replies: [] });
+          if (m.optionId) option(m.optionId).comments++;
+          log('📍 Pin ' + n + ' on ' + m.pin.selector + ' (' + Math.round(m.pin.x * 100) + '%, ' + Math.round(m.pin.y * 100) + '%) at ' + m.pin.viewportWidth + 'px: "' + body + '"', id);
+        } else if (m.optionId) {
+          option(m.optionId).comments++;
+          log('💬 On ' + name(m.optionId) + ': "' + body + '"');
+        } else {
+          log('💬 "' + body + '"');
+        }
+        // Nothing is saved in a preview, so it always "saved" — the composer
+        // needs an answer either way or it sits there saying Saving….
+        post({ type: 'comment-result', ok: true, error: null });
+        push();
+        break;
+      }
+      case 'focus-pin':
+        for (const li of list.querySelectorAll('li.focus')) li.classList.remove('focus');
+        list.querySelector('[data-pin="' + CSS.escape(m.pinId) + '"]')?.classList.add('focus');
+        break;
+      case 'unplaced-pins': { const key = m.pinIds.join(','); if (key && key !== lastUnplaced) log('⚠ Can’t place ' + m.pinIds.join(', ') + ' on this page — the element moved'); lastUnplaced = key; break; }
+      case 'delete-comment': {
+        // The whole thread goes, the way it does for real.
+        const before = state.pins.length;
+        state.pins = state.pins.filter((p) => p.id !== m.commentId);
+        for (const p of state.pins) p.replies = p.replies.filter((r) => r.id !== m.commentId);
+        let cleared = false;
+        for (const o of Object.values(state.options)) {
+          const kept = o.reactions.filter((r) => r.id !== m.commentId);
+          cleared = cleared || kept.length !== o.reactions.length;
+          o.reactions = kept;
+          for (const r of o.reactions) r.replies = r.replies.filter((x) => x.id !== m.commentId);
+          o.up = o.reactions.filter((r) => r.reaction === 'up').length;
+          o.down = o.reactions.filter((r) => r.reaction === 'down').length;
+          o.mine = (o.reactions.find((r) => r.mine) || {}).reaction || null;
+        }
+        log(cleared ? '🗑 Cleared a reaction' : before === state.pins.length ? '🗑 Deleted a reply' : '🗑 Deleted a comment and everything under it');
+        push();
+        break;
+      }
+    }
+  });
+
+  document.getElementById('phone').addEventListener('click', (e) => {
+    const on = frame.classList.toggle('phone');
+    e.currentTarget.setAttribute('aria-pressed', String(on));
+  });
+  document.getElementById('reset').addEventListener('click', () => { state = { options: {}, pins: [] }; list.innerHTML = ''; push(); });
+</script>
+</body></html>`;
+}
+//# sourceMappingURL=proof-preview.js.map

package/dist/lib/proof-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-preview.js","sourceRoot":"","sources":["../../src/lib/proof-preview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AAEpF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAEjF;;;;;;;;;;GAUG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAAG,6DAA6D,CAAC;AACzF,MAAM,MAAM,GAAG,WAAW,CAAC;AAC3B,MAAM,YAAY,GAAG,kBAAkB,CAAC;AACxC;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,wBAAwB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,4IAA4I,CAAC,CAAC;IAChK,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,gBAAgB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,aAAa,CAAC;IAC5E,MAAM,EAAE,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,OAAO;QAAE,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,GAAG,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,SAAS,cAAc,CAAC,WAAmB;IACzC,OAAO;QACL,cAAc,EAAE,WAAW;QAC3B,yBAAyB,EAAE,WAAW;QACtC,iBAAiB,EAAE,aAAa;QAChC,wBAAwB,EAAE,SAAS;QACnC,0DAA0D;QAC1D,eAAe,EAAE,UAAU;KAC5B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,WAAmB;IACjE,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACvI,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAKlC;IACC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,IAAI,iBAAiB,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,GAAoB,EAAE,GAAmB,EAAE,EAAE;QACxE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,OAA+B,EAAE,IAAsB,EAAE,EAAE;YACvF,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;QAEF,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvD,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;YAC3C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACjB,IAAI,CAAC;oBACH,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;oBACxD,IAAI,OAAO,IAAI,KAAK,QAAQ;wBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;gBACzD,CAAC;gBAAC,MAAM,CAAC;oBACP,2DAA2D;gBAC7D,CAAC;gBACD,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,EAAE,sBAAsB,CAAC,CAAC;QAE9H,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE,eAAe,EAAE,UAAU,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/H,IAAI,GAAG,CAAC,QAAQ,KAAK,UAAU,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,GAAG,MAAM,GAAG,UAAU,EAAE,EAAE,CAAC,CAAC;QACrH,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,2BAA2B,CAAC,EAAE,aAAa,CAAC,CAAC;QAEnH,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,IAAI,KAAK,YAAY;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,gCAAgC,CAAC,EAAE,OAAO,CAAC,CAAC;QAEvG,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5C,MAAM,WAAW,GAAG,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1B,qEAAqE;YACrE,oEAAoE;YACpE,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,2BAA2B,CAAC,EAAE,sBAAsB,IAAI,IAAI,CAAC,CAAC;QAChG,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjH,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,OAAO,CAAO,CAAC,aAAa,EAAE,MAAM,EAAE,EAAE;QAChD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,0DAA0D;QAC1D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,EAAiB,CAAC;IACjD,OAAO;QACL,GAAG,EAAE,oBAAoB,IAAI,GAAG;QAChC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;KACrE,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;AACzH,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,MAAc;IAC/B,OAAO;;mBAEU,UAAU,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;kDAuBa,MAAM,GAAG,UAAU;;0BAE3C,UAAU,CAAC,MAAM,CAAC;;;;;;;;oDAQQ,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;8DA2BN,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eA6F/D,CAAC;AAChB,CAAC"}

package/dist/lib/proof-push.d.ts

@@ -0,0 +1,42 @@
+import type { ProofStagedUpload, ProofVersionDetail, ScribeClient } from './client.js';
+import type { ProofFile, ProofRef } from './proof-folder.js';
+export type ProofApi = Pick<ScribeClient, 'stageProofVersion' | 'finalizeProofVersion' | 'getProofVersion' | 'downloadProofFile'>;
+/**
+ * PUTs one blob to its presigned URL. Not through `ScribeClient`: the URL is
+ * storage's, not Scribe's, and must not carry the API token.
+ *
+ * `content-length` is left for fetch to set from the body: it's signed into
+ * the URL, and the body is exactly the declared bytes, so the two agree.
+ */
+export declare function uploadBlob(upload: ProofStagedUpload, bytes: Uint8Array, fetchImpl?: typeof fetch): Promise<void>;
+export interface PushOutcome {
+    version: ProofVersionDetail;
+    previewUrl: string;
+    uploaded: number;
+    reused: number;
+}
+export declare function pushProof(args: {
+    api: ProofApi;
+    ref: ProofRef;
+    files: ProofFile[];
+    note?: string;
+    onUpload?: (path: string) => void;
+    upload?: (upload: ProofStagedUpload, bytes: Uint8Array) => Promise<void>;
+}): Promise<PushOutcome>;
+/**
+ * Downloads one version into `dir`, checking each file against its hash.
+ * Refuses a folder that already has files in it unless `force`, so a pull can
+ * never quietly overwrite the work in Ashley's current Proof folder.
+ */
+export declare function pullProof(args: {
+    api: ProofApi;
+    ref: ProofRef;
+    version: number | 'draft';
+    dir: string;
+    force?: boolean;
+}): Promise<ProofVersionDetail>;
+/** A pull that was refused before anything was downloaded. */
+export declare class PullRefused extends Error {
+}
+export declare function defaultPullDir(cwd: string, ref: ProofRef, version: number | 'draft'): string;
+//# sourceMappingURL=proof-push.d.ts.map

package/dist/lib/proof-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-push.d.ts","sourceRoot":"","sources":["../../src/lib/proof-push.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAe7D,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,sBAAsB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC,CAAC;AAElI;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7H;AAUD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,EAAE,QAAQ,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E,GAAG,OAAO,CAAC,WAAW,CAAC,CAmBvB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,EAAE,QAAQ,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsB9B;AAED,8DAA8D;AAC9D,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAE5F"}

package/dist/lib/proof-push.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+/**
+ * RFC 0029 — moving a Proof's files between Ashley's folder and Scribe.
+ *
+ * A push is three calls: declare the files (the server answers with upload
+ * URLs for the ones it doesn't have), upload those straight to storage, then
+ * finalize (the server checks each upload's size and hash and makes it the
+ * draft). Unchanged files are never re-sent, because the server already holds
+ * them under their hash.
+ */
+/** How many uploads run at once. Enough to hide latency, few enough not to swamp a home connection. */
+const UPLOAD_CONCURRENCY = 4;
+/**
+ * PUTs one blob to its presigned URL. Not through `ScribeClient`: the URL is
+ * storage's, not Scribe's, and must not carry the API token.
+ *
+ * `content-length` is left for fetch to set from the body: it's signed into
+ * the URL, and the body is exactly the declared bytes, so the two agree.
+ */
+export async function uploadBlob(upload, bytes, fetchImpl = fetch) {
+    const headers = Object.fromEntries(Object.entries(upload.headers).filter(([name]) => name.toLowerCase() !== 'content-length'));
+    // Copied into a fresh ArrayBuffer-backed array: fetch's body type rejects a
+    // Uint8Array over a possibly-shared buffer, which is what readFileSync's is typed as.
+    const res = await fetchImpl(upload.url, { method: 'PUT', headers, body: new Uint8Array(bytes) });
+    if (!res.ok) {
+        const detail = (await res.text().catch(() => '')).slice(0, 300);
+        throw new Error(`Uploading ${upload.path} failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
+    }
+}
+async function inBatches(items, size, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.min(size, items.length) }, async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    });
+    await Promise.all(workers);
+}
+export async function pushProof(args) {
+    const { api, ref, files } = args;
+    const upload = args.upload ?? ((u, bytes) => uploadBlob(u, bytes));
+    const staged = await api.stageProofVersion(ref.client, ref.proof, {
+        manifest: files.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })),
+        note: args.note ?? null,
+    });
+    const byHash = new Map(files.map((f) => [f.sha256, f]));
+    await inBatches(staged.uploads, UPLOAD_CONCURRENCY, async (u) => {
+        const file = byHash.get(u.sha256);
+        if (!file)
+            throw new Error(`The server asked for a file this folder doesn't have (${u.path})`);
+        await upload(u, readFileSync(file.absolute));
+        args.onUpload?.(u.path);
+    });
+    const finalized = await api.finalizeProofVersion(ref.client, ref.proof);
+    return { version: finalized.version, previewUrl: finalized.previewUrl, uploaded: staged.uploads.length, reused: staged.reused };
+}
+/**
+ * Downloads one version into `dir`, checking each file against its hash.
+ * Refuses a folder that already has files in it unless `force`, so a pull can
+ * never quietly overwrite the work in Ashley's current Proof folder.
+ */
+export async function pullProof(args) {
+    const { api, ref } = args;
+    const dir = resolve(args.dir);
+    if (existsSync(dir) && readdirSync(dir).length > 0 && !args.force) {
+        throw new PullRefused(`${dir} isn't empty. Pull into a new folder, or pass --force to overwrite.`);
+    }
+    const version = await api.getProofVersion(ref.client, ref.proof, args.version);
+    for (const entry of version.manifest) {
+        const target = resolve(dir, ...entry.path.split('/'));
+        // The server validates paths at push time; this is the client's own check
+        // that a manifest can't write outside the folder it was asked to fill.
+        if (!target.startsWith(dir + sep))
+            throw new Error(`Refusing to write ${entry.path} outside ${dir}`);
+        const bytes = await api.downloadProofFile(ref.client, ref.proof, version.number, entry.path);
+        const sha = createHash('sha256').update(bytes).digest('hex');
+        if (sha !== entry.sha256)
+            throw new Error(`${entry.path} arrived corrupted (hash mismatch) — try the pull again`);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, bytes);
+    }
+    return version;
+}
+/** A pull that was refused before anything was downloaded. */
+export class PullRefused extends Error {
+}
+export function defaultPullDir(cwd, ref, version) {
+    return join(cwd, `${ref.proof}-${version === 'draft' ? 'draft' : `v${version}`}`);
+}
+//# sourceMappingURL=proof-push.js.map

package/dist/lib/proof-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-push.js","sourceRoot":"","sources":["../../src/lib/proof-push.ts"],"names":[],"mappings":"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"}

package/dist/lib/skill.d.ts

@@ -42,4 +42,17 @@ export declare function installSkill(options?: {
 }): SkillInstallResult;
 /** Shortens a path for display, so output reads `~/.claude/skills/...`. */
 export declare function tildify(path: string): string;
+/**
+ * Installs the bundled skill and says what happened in one line.
+ *
+ * Called from `scribe login` as well as `scribe update`, so setting up a
+ * machine is install-then-login and nothing else. Before this, the setup guide
+ * had to tell someone to run `scribe update` on a fresh install purely to copy
+ * the skill across — an `npm install -g` of the version they had just
+ * installed, to do a directory copy.
+ *
+ * Silent on a symlinked destination: that's a maintainer editing the skill in
+ * a checkout, and they don't need telling on every login.
+ */
+export declare function reportSkillInstall(): void;
 //# sourceMappingURL=skill.d.ts.map

package/dist/lib/skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"AAKA,sFAAsF;AACtF,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAEhD,6DAA6D;AAC7D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAOhD;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAWjC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,kBAAkB,CAaxG;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5C"}
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"AAKA,sFAAsF;AACtF,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAEhD,6DAA6D;AAC7D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAOhD;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAWjC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,kBAAkB,CA0BxG;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAOzC"}

package/dist/lib/skill.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, lstatSync, mkdirSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -58,8 +58,18 @@ export function installSkill(options = {}) {
     if (existing?.isSymbolicLink())
         return { status: 'symlink', dest };
     mkdirSync(dirname(dest), { recursive: true });
+    // Staged beside the destination and swapped in, rather than removed and
+    // re-copied in place. Claude Code reads this directory, and a session that
+    // looks during a remove-then-copy finds a skill that has no SKILL.md or no
+    // recipes — briefly, but on a machine where the update runs at session start
+    // that window overlaps exactly the moment something is reading.
+    const staging = `${dest}.scribe-tmp`;
+    rmSync(staging, { recursive: true, force: true });
+    cpSync(source, staging, { recursive: true });
+    // `rename` onto a non-empty directory fails, so the old copy goes first.
+    // The gap between these two is a rename, not a recursive file copy.
     rmSync(dest, { recursive: true, force: true });
-    cpSync(source, dest, { recursive: true });
+    renameSync(staging, dest);
     return { status: 'installed', dest };
 }
 /** Shortens a path for display, so output reads `~/.claude/skills/...`. */
@@ -67,4 +77,25 @@ export function tildify(path) {
     const home = homedir();
     return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
 }
+/**
+ * Installs the bundled skill and says what happened in one line.
+ *
+ * Called from `scribe login` as well as `scribe update`, so setting up a
+ * machine is install-then-login and nothing else. Before this, the setup guide
+ * had to tell someone to run `scribe update` on a fresh install purely to copy
+ * the skill across — an `npm install -g` of the version they had just
+ * installed, to do a directory copy.
+ *
+ * Silent on a symlinked destination: that's a maintainer editing the skill in
+ * a checkout, and they don't need telling on every login.
+ */
+export function reportSkillInstall() {
+    const skill = installSkill();
+    if (skill.status === 'installed') {
+        console.log(`Skill: installed scribe-site-builder to ${tildify(skill.dest)}.`);
+    }
+    else if (skill.status === 'missing-source') {
+        console.warn("Skill: this install is missing its bundled copy of scribe-site-builder — tell Dave.");
+    }
+}
 //# sourceMappingURL=skill.js.map

package/dist/lib/skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAc,MAAM,SAAS,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,sFAAsF;AACtF,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;QAC5C,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;KACzD,CAAC;IACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACzF,CAAC;AAOD,0FAA0F;AAC1F,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,UAAqD,EAAE;IAClF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,EAAE,CAAC;IAEhD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEjD,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,EAAE,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAEnE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC"}
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"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"}

package/dist/lib/update-check.d.ts

@@ -0,0 +1,46 @@
+export declare const PACKAGE_NAME = "@scribe-platform/cli";
+/**
+ * Compares two dotted numeric versions. Returns true when `candidate` is newer
+ * than `current`.
+ *
+ * Deliberately not a semver dependency: this package publishes plain
+ * `major.minor.patch` and the one judgement call — what to do with a
+ * prerelease suffix — is answered by ignoring it. A `0.8.0-beta.1` compares
+ * equal to `0.8.0`, so someone already on the beta is not told to "update" to
+ * the release they effectively have, and someone on `0.7.0` is offered it.
+ * Shipping a prerelease to `latest` is not something this project does.
+ */
+export declare function isNewer(candidate: string, current: string): boolean;
+export interface UpdateCheck {
+    current: string;
+    /** Null when the registry couldn't be reached. */
+    latest: string | null;
+    updateAvailable: boolean;
+    /**
+     * False when the registry could not be reached.
+     *
+     * Reported separately from `latest` so a caller can't say "up to date" when
+     * it means "couldn't ask" — the two are the same shape and only one of them
+     * is a fact.
+     */
+    reachable: boolean;
+}
+/**
+ * Whether a newer CLI has been published.
+ *
+ * Runs on **every** session start, with no cache. An earlier version cached
+ * the answer for a day to keep a round trip off the front of each
+ * conversation; measuring it made that look like the wrong trade — 210ms
+ * against being up to a day late on a fix, plus a cache that silently
+ * swallowed the environment override this is tested with. Checking every time
+ * is both faster to the user and less code.
+ */
+export declare function checkForUpdate(current: string): Promise<UpdateCheck>;
+/**
+ * What `npm install -g` is pointed at.
+ *
+ * Overridable so the whole update path can be exercised against a local
+ * `npm pack` tarball before anything is published — see TESTING-UPDATES.md.
+ */
+export declare function installSpec(): string;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/lib/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/lib/update-check.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,yBAAyB,CAAC;AAsBnD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBnE;AAuBD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAe1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}