@quadient/skillshare 1.4.0 → 1.6.0

package/README.md

@@ -209,3 +209,70 @@ bun run publish:tui -- --otp 123456
 ```
 
 The publish script builds `tui/`, validates the packed files with `npm pack --dry-run`, and only then runs `npm publish`.
+
+## Pages applications
+
+`skillshare pages upload <directory> --slug <slug>` accepts static sites or
+Wrangler JSON/JSONC projects. The CLI bundles Worker dependencies locally; install
+them and build frontend assets before uploading. Inspect process status and logs
+with `skillshare pages runtime <slug>`. Pages are served below `/p/<slug>/`, so use
+that base path when building assets. Runtime data survives content replacement.
+
+## Local Pages development (1.6.0+)
+
+Run a celld application without a SkillShare server, repository checkout, Docker,
+cloud storage account or CLI login:
+
+```sh
+bunx @quadient/skillshare@^1.6.0 pages dev . --slug my-app
+```
+
+The directory must contain one `wrangler.json` or `wrangler.jsonc`. The CLI downloads
+and verifies celld 0.4.1 on first use, caches it under `~/.cache/skillshare/celld`,
+and uses its packaged esbuild. Supported hosts are macOS Apple Silicon and Linux
+x64/ARM64; Windows users can use WSL2. `--celld <executable>` or `CELLD_EXECUTABLE`
+selects an existing installation.
+
+The default URL is `http://127.0.0.1:8787/p/my-app/`. The proxy removes the Page prefix
+and adds the same `X-Skillshare-*` request headers as SkillShare. The development
+revision is `0`. The toolbar offers four local users covering every role combination: Alice
+(owner), Bob (neither role), Charlie (admin), and Dana (owner and admin).
+Each option shows explicit `isOwner` and `isAdmin` values, and each browser can
+select its own user. Customize the first
+user with `--user-id`, `--user-name` and `--user-email`. This is simulated local
+identity, not a real SSO login. Listeners bind only to loopback.
+
+The proxy filters SkillShare authentication cookies and Authorization on ordinary
+routes, scopes application cookies and redirects to the Page, and supports HTTP
+streaming and WebSockets. `/api/bypass-sso/*` preserves Authorization but forwards
+no cookies or user identity, matching hosted Pages. Application `vars` and resource
+bindings still come from Wrangler. Host cloud credentials and CLI tokens are not
+passed to the celld process.
+
+For a project with a build step (React/Vite, for example):
+
+```sh
+bunx @quadient/skillshare@^1.6.0 pages dev dist \
+  --watch-dir . --build "bun run build" --slug my-app --port 8787
+```
+
+`--build` runs in `--watch-dir` before the first start and after source changes.
+The command is executed through your shell. The build must produce the complete
+application directory, including Wrangler configuration, Worker and assets.
+Source edits are debounced and builds are serialized. The output directory,
+`node_modules`, `.git`, `.celld`, `.wrangler`, `.skillshare`, `dist` subdirectories
+and `coverage` are ignored to avoid rebuild loops. Use a dedicated output directory;
+do not write generated files alongside watched source files.
+
+After a successful build the CLI gracefully restarts celld and reloads open pages
+once the new node is ready. Local resources persist in the application's `.celld/`
+directory. Do not delete that directory in your build script. A build failure leaves
+the previous node serving; a celld startup failure leaves the proxy available with
+an error page. Fixing a watched source file retries the build/start. The terminal
+shows errors. Ctrl+C stops the watcher, proxy and child processes.
+
+Browser reload uses a script injected into HTML and a same-origin SSE connection.
+This is full-page reload, not React HMR. A CSP that disallows same-origin scripts
+or connections must be adjusted for local development or the page reloaded manually.
+The `/__skillshare_dev/` path is reserved for local development controls. This command
+does not implement the SkillShare catalog, actual SSO or cloud deployment.

package/dist/index.js

@@ -1,3 +1,5 @@
+import { preparePageFiles } from './pages.js';
+import { runPageDev } from './pages-dev.js';
 import { createServer } from 'node:http';
 import { createHash, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
@@ -81,6 +83,9 @@ Commands:
   pages list
   pages show <slug>
   pages upload <directory> [--slug <slug>]
+  pages dev [directory] [--slug <slug>] [--port <port>]
+    [--build <command> --watch-dir <sources>] [--celld <executable>]
+    [--user-id <id>] [--user-name <name>] [--user-email <email>]
   git configure [local]
   git unconfigure [local]
 
@@ -99,6 +104,10 @@ async function main() {
         process.exit(0);
     }
     const options = await parseOptions(args.slice(1));
+    if ((command === 'pages' || command === 'page') && options.positionals[0] === 'dev') {
+        await runPageDev(options.positionals[1] ?? '.', options.flags);
+        return;
+    }
     switch (command) {
         case 'login': {
             await login(options.positionals[0] === 'local' ? LOCAL_URL : PROD_URL);
@@ -280,15 +289,15 @@ async function main() {
                     if (action === 'list') {
                         const pages = await client.get('/api/pages');
                         for (const page of pages) {
-                            console.log(`${page.slug}\t${page.fileCount}\t${page.ownerDisplayName}`);
+                            console.log(`${page.slug}\t${page.kind}\t${page.fileCount}\t${page.ownerDisplayName}`);
                         }
                         return;
                     }
-                    if (action === 'show') {
+                    if (action === 'show' || action === 'runtime') {
                         const slug = options.positionals[1];
                         if (!slug)
-                            throw new Error('pages show requires <slug>');
-                        console.log(JSON.stringify(await client.get(`/api/pages/${encodeURIComponent(slug)}`), null, 2));
+                            throw new Error(`pages ${action} requires <slug>`);
+                        console.log(JSON.stringify(await client.get(`/api/pages/${encodeURIComponent(slug)}${action === 'runtime' ? '/runtime' : ''}`), null, 2));
                         return;
                     }
                     if (action === 'upload') {
@@ -311,7 +320,7 @@ async function main() {
                         }
                         return;
                     }
-                    throw new Error(`Unknown pages command '${action}'. Use list, show, or upload.`);
+                    throw new Error(`Unknown pages command '${action}'. Use list, show, runtime, or upload.`);
                 }
             }
             return;
@@ -796,17 +805,14 @@ async function loadLocalSkillContext(directory, baseUrl) {
     };
 }
 async function loadLocalPageFiles(directory) {
-    const filePlans = await collectFilePlans(directory, directory, { includeSkillMetadata: true });
+    const filePlans = await collectFilePlans(directory, directory, { includeSkillMetadata: true, pageProject: true });
     if (filePlans.length === 0) {
         throw new Error('The page directory is empty.');
     }
-    if (!filePlans.some((file) => file.relativePath === 'index.html')) {
-        throw new Error('The page directory must contain index.html at its root.');
-    }
-    const totalBytes = filePlans.reduce((sum, file) => sum + file.size, 0);
+    const files = await preparePageFiles(directory, await collectFiles(filePlans));
     return {
-        files: await collectFiles(filePlans),
-        totalBytes,
+        files,
+        totalBytes: files.reduce((sum, file) => sum + file.content.length, 0),
     };
 }
 async function createSkillFromDirectory(client, localSkill, input) {
@@ -1881,6 +1887,8 @@ async function collectFilePlans(root, current = root, options = {}) {
     const files = [];
     for (const entry of entries) {
         const entryPath = join(current, entry.name);
+        if (options.pageProject && (entry.isSymbolicLink() || ['.git', '.celld', '.wrangler', 'node_modules'].includes(entry.name)))
+            continue;
         if (entry.isDirectory()) {
             files.push(...(await collectFilePlans(root, entryPath, options)));
             continue;

package/dist/pages-dev-proxy.js

@@ -0,0 +1,308 @@
+import { createServer, request as httpRequest, } from 'node:http';
+const sessionCookie = 'skillshare.dev-user';
+const internal = '/__skillshare_dev';
+const hostCookie = (name) => name.startsWith('skillshare.auth') ||
+    name.startsWith('.AspNetCore.') ||
+    name === sessionCookie;
+const hopHeaders = [
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+];
+function cleanHeaders(headers) {
+    const result = { ...headers };
+    for (const name of [
+        ...hopHeaders,
+        ...(headers.connection ?? '')
+            .split(',')
+            .map((name) => name.trim().toLowerCase()),
+    ])
+        delete result[name];
+    return result;
+}
+export function requestHeaders(request, user, baseUrl, slug) {
+    const headers = cleanHeaders(request.headers);
+    for (const name of Object.keys(headers))
+        if (name.startsWith('x-skillshare-') ||
+            name.startsWith('x-forwarded-') ||
+            name === 'forwarded')
+            delete headers[name];
+    delete headers.host;
+    delete headers.cookie;
+    headers['accept-encoding'] = 'identity';
+    if (user) {
+        delete headers.authorization;
+        headers['x-skillshare-user'] = Buffer.from(JSON.stringify(user)).toString('base64');
+        const cookies = (request.headers.cookie ?? '')
+            .split(';')
+            .map((value) => value.trim())
+            .filter((value) => value && !hostCookie(value.split('=')[0]));
+        if (cookies.length)
+            headers.cookie = cookies.join('; ');
+    }
+    headers['x-skillshare-page'] = slug;
+    headers['x-skillshare-revision'] = '0';
+    headers['x-skillshare-base-url'] = baseUrl;
+    return headers;
+}
+export function responseCookies(cookies, prefix) {
+    return cookies
+        .filter((cookie) => !hostCookie(cookie.split('=')[0].trim()))
+        .map((cookie) => {
+        let path = '/';
+        const fields = cookie.split(';').filter((field, index) => {
+            if (!index)
+                return true;
+            if (/^\s*domain\s*=/i.test(field))
+                return false;
+            if (/^\s*path\s*=/i.test(field)) {
+                path = field.slice(field.indexOf('=') + 1).trim();
+                return false;
+            }
+            return true;
+        });
+        return (fields.join(';') +
+            '; Path=' +
+            prefix +
+            (path.startsWith('/') ? path : '/'));
+    });
+}
+export function createDevProxy(options) {
+    const prefix = `/p/${options.slug}`;
+    const streams = new Set();
+    const upgrades = new Set();
+    const userFor = (request) => {
+        const id = (request.headers.cookie ?? '')
+            .split(';')
+            .map((value) => value.trim())
+            .find((value) => value.startsWith(sessionCookie + '='))
+            ?.slice(sessionCookie.length + 1);
+        return (options.users.find((user) => encodeURIComponent(user.id) === id) ??
+            options.users[0]);
+    };
+    function pagePath(path) {
+        return path.startsWith(prefix + '/') ? path.slice(prefix.length) : undefined;
+    }
+    function allowed(request) {
+        const host = request.headers.host ?? '';
+        return /^(127\.0\.0\.1|localhost)(:\d+)?$/.test(host);
+    }
+    const server = createServer((request, response) => {
+        if (!allowed(request)) {
+            response.writeHead(403).end('Local requests only');
+            return;
+        }
+        const url = new URL(request.url, `http://${request.headers.host}`);
+        if (url.pathname === '/' || url.pathname === prefix) {
+            response.writeHead(307, { Location: prefix + '/' + url.search }).end();
+            return;
+        }
+        if (url.pathname.startsWith(internal + '/')) {
+            if (request.method !== 'GET') {
+                response.writeHead(405).end();
+                return;
+            }
+            if (url.pathname === internal + '/events') {
+                response.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-store',
+                    Connection: 'keep-alive',
+                });
+                streams.add(response);
+                response.write(`data: ${options.generation()}\n\n`);
+                response.on('close', () => streams.delete(response));
+                return;
+            }
+            if (url.pathname === internal + '/user') {
+                // Only same-origin browser navigation may switch the local identity.
+                if (request.headers['sec-fetch-site'] === 'cross-site') {
+                    response.writeHead(403).end();
+                    return;
+                }
+                const user = options.users.find((user) => user.id === url.searchParams.get('id'));
+                if (!user) {
+                    response.writeHead(400).end('Unknown development user');
+                    return;
+                }
+                response
+                    .writeHead(303, {
+                    Location: prefix + '/',
+                    'Set-Cookie': `${sessionCookie}=${encodeURIComponent(user.id)}; Path=${prefix}/; HttpOnly; SameSite=Strict`,
+                    'Cache-Control': 'no-store',
+                })
+                    .end();
+                return;
+            }
+            if (url.pathname === internal + '/client.js') {
+                response.writeHead(200, {
+                    'Content-Type': 'text/javascript; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                });
+                response.end(`(() => {
+const version = new URL(document.currentScript.src).searchParams.get('version');
+const events = new EventSource(${JSON.stringify(internal + '/events')});
+events.onmessage = event => { if (event.data !== version) location.reload(); };
+const bar = document.createElement('div');
+bar.style.cssText = 'position:fixed;bottom:12px;right:12px;z-index:2147483647;background:#182924;color:white;padding:10px 14px;border-radius:10px;font:13px system-ui;box-shadow:0 2px 12px #0003';
+const label = document.createElement('label'); label.textContent = 'SkillShare dev · ';
+const select = document.createElement('select'); select.setAttribute('aria-label', 'Development user');
+for (const user of ${JSON.stringify(options.users.map(({ id, displayName, isOwner, isAdmin }) => ({ id, displayName, isOwner, isAdmin })))}) {
+ const option = document.createElement('option'); option.value = user.id; option.textContent = user.displayName + ' (isOwner=' + user.isOwner + ', isAdmin=' + user.isAdmin + ')'; select.append(option);
+}
+select.value = new URL(document.currentScript.src).searchParams.get('user');
+select.onchange = () => { location.href = ${JSON.stringify(internal + '/user?id=')} + encodeURIComponent(select.value); };
+label.append(select); bar.append(label); document.body.append(bar);
+})();`);
+                return;
+            }
+            response.writeHead(404).end();
+            return;
+        }
+        const path = pagePath(url.pathname);
+        if (!path) {
+            response.writeHead(404).end('Use ' + prefix + '/');
+            return;
+        }
+        const target = options.target();
+        if (!target) {
+            response.writeHead(500, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-store',
+            });
+            response.end(`<p>Page backend is rebuilding. Check your terminal for errors.</p><script src="${internal}/client.js?version=${options.generation()}&user=${encodeURIComponent(userFor(request).id)}"></script>`);
+            return;
+        }
+        const bypass = path === '/api/bypass-sso' || path.startsWith('/api/bypass-sso/');
+        if (!bypass &&
+            !['GET', 'HEAD'].includes(request.method ?? '') &&
+            (request.headers['sec-fetch-site'] === 'cross-site' ||
+                (request.headers.origin && request.headers.origin !== url.origin))) {
+            response.writeHead(403).end('Cross-origin mutation rejected');
+            return;
+        }
+        const user = bypass ? undefined : userFor(request);
+        const upstream = httpRequest(new URL(path + url.search, target), {
+            method: request.method,
+            headers: requestHeaders(request, user, url.origin + prefix + '/', options.slug),
+        }, (incoming) => {
+            const headers = cleanHeaders(incoming.headers);
+            headers['cache-control'] = 'private, no-cache';
+            if (headers['set-cookie'])
+                headers['set-cookie'] = responseCookies(headers['set-cookie'], prefix);
+            if (headers.location) {
+                if (headers.location.startsWith('/') &&
+                    !headers.location.startsWith('//'))
+                    headers.location = prefix + headers.location;
+                else if (headers.location.startsWith(target + '/'))
+                    headers.location =
+                        url.origin + prefix + headers.location.slice(target.length);
+            }
+            const inject = request.method !== 'HEAD' &&
+                incoming.statusCode === 200 &&
+                !headers['content-encoding'] &&
+                headers['content-type']?.includes('text/html');
+            const failed = () => {
+                if (!response.headersSent)
+                    response.writeHead(502);
+                response.end();
+            };
+            incoming.on('error', failed);
+            if (inject) {
+                const chunks = [];
+                incoming.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+                incoming.on('end', () => {
+                    delete headers['content-length'];
+                    delete headers.etag;
+                    const html = Buffer.concat(chunks).toString('utf8');
+                    const script = `<script src="${internal}/client.js?version=${options.generation()}&user=${encodeURIComponent(userFor(request).id)}"></script>`;
+                    response.writeHead(incoming.statusCode, headers);
+                    response.end(html.includes('</body>')
+                        ? html.replace('</body>', script + '</body>')
+                        : html + script);
+                });
+            }
+            else {
+                response.writeHead(incoming.statusCode ?? 502, headers);
+                incoming.pipe(response);
+            }
+        });
+        upstream.on('error', () => {
+            if (!response.headersSent)
+                response.writeHead(502);
+            response.end('Page connection failed');
+        });
+        response.on('close', () => upstream.destroy());
+        request.pipe(upstream);
+    });
+    server.on('upgrade', (request, socket, head) => {
+        const target = options.target();
+        const url = new URL(request.url, `http://${request.headers.host}`);
+        const path = pagePath(url.pathname);
+        if (!allowed(request) ||
+            !path ||
+            !target ||
+            (request.headers.origin && request.headers.origin !== url.origin)) {
+            socket.destroy();
+            return;
+        }
+        const bypass = path === '/api/bypass-sso' || path.startsWith('/api/bypass-sso/');
+        const headers = requestHeaders(request, bypass ? undefined : userFor(request), url.origin + prefix + '/', options.slug);
+        headers.connection = 'Upgrade';
+        headers.upgrade = request.headers.upgrade;
+        const upstream = httpRequest(new URL(path + url.search, target), {
+            headers,
+        });
+        upstream.on('upgrade', (incoming, peer, peerHead) => {
+            upgrades.add(socket);
+            upgrades.add(peer);
+            socket.on('close', () => {
+                upgrades.delete(socket);
+                peer.destroy();
+            });
+            peer.on('close', () => {
+                upgrades.delete(peer);
+                socket.destroy();
+            });
+            socket.on('error', () => peer.destroy());
+            peer.on('error', () => socket.destroy());
+            const responseHeaders = { ...incoming.headers };
+            if (responseHeaders['set-cookie'])
+                responseHeaders['set-cookie'] = responseCookies(responseHeaders['set-cookie'], prefix);
+            socket.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(responseHeaders)
+                .flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((v) => `${key}: ${v}`))
+                .join('\r\n')}\r\n\r\n`);
+            if (head.length)
+                peer.write(head);
+            if (peerHead.length)
+                socket.write(peerHead);
+            socket.pipe(peer).pipe(socket);
+        });
+        upstream.on('response', (incoming) => {
+            incoming.resume();
+            socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n');
+        });
+        upstream.on('error', () => socket.destroy());
+        socket.on('error', () => upstream.destroy());
+        upstream.end();
+    });
+    return {
+        server,
+        reload() {
+            for (const response of streams)
+                response.write(`data: ${options.generation()}\n\n`);
+        },
+        async close() {
+            for (const response of streams)
+                response.end();
+            for (const socket of upgrades)
+                socket.destroy();
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/pages-dev-tools.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+const release = '0.4.1';
+const platforms = {
+    'darwin-arm64': [
+        'aarch64-apple-darwin',
+        '95c689769f66c08fd0d191fbfc731adb4c8340b49678b11979698ecf2e73393d',
+    ],
+    'linux-x64': [
+        'x86_64-unknown-linux-gnu',
+        '7b42a410e340bca4dbadd08ecb7f8983854aa855aa7467c29ab0e08b8b7f2007',
+    ],
+    'linux-arm64': [
+        'aarch64-unknown-linux-gnu',
+        '5cc2281493a896b2cc7c7b6c46b2188753832d6b028457338c8eea774a1dd9a1',
+    ],
+};
+export async function ensureCelld(override, signal) {
+    if (override)
+        return override.includes('/') ? resolve(override) : override;
+    const platform = platforms[`${process.platform}-${process.arch}`];
+    if (!platform)
+        throw new Error('celld supports macOS Apple Silicon and Linux x64/ARM64. On Windows, use WSL2.');
+    const [target, checksum] = platform;
+    const directory = join(homedir(), '.cache', 'skillshare', 'celld', release, target);
+    const binary = join(directory, 'celld');
+    const archivePath = join(directory, 'celld.gz');
+    let archive;
+    try {
+        archive = await readFile(archivePath);
+    }
+    catch {
+        archive = Buffer.alloc(0);
+    }
+    if (createHash('sha256').update(archive).digest('hex') !== checksum) {
+        console.log(`Downloading celld ${release} (${target})…`);
+        const response = await fetch(`https://github.com/denoland/celld/releases/download/v${release}/celld-${target}.gz`, {
+            signal: signal ?? AbortSignal.timeout(120_000),
+        });
+        if (!response.ok)
+            throw new Error(`celld download failed: HTTP ${response.status}`);
+        archive = Buffer.from(await response.arrayBuffer());
+        if (createHash('sha256').update(archive).digest('hex') !== checksum)
+            throw new Error('celld checksum mismatch');
+    }
+    await mkdir(directory, { recursive: true });
+    const unpacked = gunzipSync(archive);
+    try {
+        if ((await readFile(binary)).equals(unpacked))
+            return binary;
+    }
+    catch { }
+    const temporary = `${binary}.${process.pid}.tmp`;
+    try {
+        await writeFile(temporary, unpacked);
+        await chmod(temporary, 0o755);
+        await rename(temporary, binary);
+        await writeFile(archivePath, archive);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return binary;
+}

package/dist/pages-dev.js

@@ -0,0 +1,363 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { access, realpath, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { basename, delimiter, dirname, relative, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { watch } from 'chokidar';
+import { ensureCelld } from './pages-dev-tools.js';
+import { createDevProxy } from './pages-dev-proxy.js';
+export function createDevUsers(options = {}) {
+    const users = [{
+            id: options.userId ?? '1',
+            displayName: options.userName ?? 'Alice Morgan',
+            email: options.userEmail ?? 'alice@example.test',
+            isOwner: true, isAdmin: false,
+        }];
+    let nextId = 2;
+    for (const user of [
+        { displayName: 'Bob Taylor', email: 'bob@example.test', isOwner: false, isAdmin: false },
+        { displayName: 'Charlie Parker', email: 'charlie@example.test', isOwner: false, isAdmin: true },
+        { displayName: 'Dana Wilson', email: 'dana@example.test', isOwner: true, isAdmin: true },
+    ]) {
+        while (users.some(existing => existing.id === String(nextId)))
+            nextId++;
+        users.push({ id: String(nextId++), ...user });
+    }
+    return users;
+}
+async function freePort() {
+    const server = createServer();
+    server.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    const port = server.address().port;
+    await new Promise((resolve) => server.close(() => resolve()));
+    return port;
+}
+async function stop(child) {
+    if (!child || child.exitCode !== null || child.signalCode !== null)
+        return;
+    const exited = once(child, 'exit').catch(() => { });
+    const signal = (value) => {
+        try {
+            if (child.pid)
+                process.kill(-child.pid, value);
+        }
+        catch {
+            child.kill(value);
+        }
+    };
+    signal('SIGTERM');
+    const timer = setTimeout(() => signal('SIGKILL'), 5000);
+    try {
+        await exited;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function startPageDev(options) {
+    const requestedDirectory = resolve(options.directory);
+    const directory = await realpath(requestedDirectory).catch(async () => resolve(await realpath(dirname(requestedDirectory)), basename(requestedDirectory)));
+    const watchDirectory = await realpath(resolve(options.watchDirectory ?? directory));
+    const slug = options.slug ??
+        (basename(directory) === 'dist'
+            ? basename(dirname(directory))
+            : basename(directory));
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(slug))
+        throw new Error('Use --slug with 1–64 lowercase letters, numbers or hyphens.');
+    const port = options.port ?? 8787;
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error('Invalid --port (expected 1–65535).');
+    const executable = await ensureCelld(options.celld ?? process.env.CELLD_EXECUTABLE, options.signal);
+    options.signal?.throwIfAborted();
+    const esbuildDirectory = dirname(createRequire(import.meta.url).resolve('esbuild/bin/esbuild'));
+    // Do not inherit host/CLI tokens or cloud storage credentials into application code.
+    const env = {
+        PATH: `${esbuildDirectory}${delimiter}${process.env.PATH ?? ''}`,
+    };
+    for (const key of [
+        'HOME',
+        'TMPDIR',
+        'TMP',
+        'TEMP',
+        'LANG',
+        'SSL_CERT_FILE',
+        'SSL_CERT_DIR',
+    ])
+        if (process.env[key])
+            env[key] = process.env[key];
+    const users = createDevUsers(options);
+    let generation = 0;
+    let lastError;
+    let address;
+    let node;
+    let build;
+    let closing = false;
+    let pending = false;
+    let work;
+    let debounce;
+    const proxy = createDevProxy({
+        slug,
+        users,
+        target: () => address,
+        generation: () => generation,
+    });
+    proxy.server.listen(port, '127.0.0.1');
+    await once(proxy.server, 'listening');
+    const publicPort = proxy.server.address().port;
+    const url = `http://127.0.0.1:${publicPort}/p/${slug}/`;
+    async function rebuild() {
+        lastError = undefined;
+        try {
+            if (options.build) {
+                console.log(`Building: ${options.build}`);
+                build = spawn(options.build, {
+                    cwd: watchDirectory,
+                    shell: true,
+                    stdio: 'inherit',
+                    detached: true,
+                    env: process.env,
+                });
+                const [code] = await once(build, 'exit');
+                build = undefined;
+                if (closing)
+                    return;
+                if (code !== 0)
+                    throw new Error('Build failed. Fix the source; watching for changes.');
+            }
+            const configurations = await Promise.all(['wrangler.json', 'wrangler.jsonc'].map(async (name) => {
+                try {
+                    await access(resolve(directory, name));
+                    return name;
+                }
+                catch {
+                    return undefined;
+                }
+            }));
+            if (configurations.filter(Boolean).length !== 1)
+                throw new Error('The application directory must contain exactly one wrangler.json or wrangler.jsonc.');
+            if (closing)
+                return;
+            address = undefined;
+            const previous = node;
+            node = undefined;
+            await stop(previous);
+            if (closing)
+                return;
+            const workerPort = await freePort();
+            if (closing)
+                return;
+            const child = (node = spawn(executable, [
+                'dev',
+                directory,
+                '--host',
+                '127.0.0.1',
+                '--port',
+                String(workerPort),
+                '--no-watch',
+            ], {
+                cwd: directory,
+                env,
+                stdio: ['ignore', 'inherit', 'inherit'],
+                detached: true,
+            }));
+            let spawnError;
+            child.on('error', (error) => {
+                spawnError = error;
+            });
+            const target = `http://127.0.0.1:${workerPort}`;
+            for (let attempt = 0; attempt < 150; attempt++) {
+                if (closing)
+                    return;
+                if (spawnError)
+                    throw spawnError;
+                if (child.exitCode !== null || child.signalCode !== null)
+                    throw new Error('celld exited. Fix the project; watching for changes.');
+                try {
+                    const result = await fetch(target + '/.well-known/celld/health', {
+                        signal: AbortSignal.timeout(1000),
+                    });
+                    await result.body?.cancel();
+                    if (result.ok) {
+                        address = target;
+                        generation++;
+                        proxy.reload();
+                        child.on('exit', () => {
+                            if (node === child && !closing) {
+                                address = undefined;
+                                console.error('celld stopped. Waiting for a source change to restart.');
+                            }
+                        });
+                        console.log(`Ready: ${url}`);
+                        return;
+                    }
+                }
+                catch { }
+                await delay(200);
+            }
+            throw new Error('celld did not become ready within the startup timeout.');
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            if (!closing)
+                console.error(lastError);
+            // A failed build leaves the previous node serving. A failed node is disposed.
+            if (!address) {
+                await stop(node);
+                node = undefined;
+            }
+        }
+    }
+    function schedule() {
+        pending = true;
+        if (work || closing)
+            return;
+        work = (async () => {
+            while (pending && !closing) {
+                pending = false;
+                await rebuild();
+            }
+        })().finally(() => {
+            work = undefined;
+        });
+    }
+    const output = directory !== watchDirectory && options.build ? directory : undefined;
+    const watcher = watch(watchDirectory, {
+        ignoreInitial: true,
+        ignored(path) {
+            const absolute = resolve(path);
+            if (output && (absolute === output || absolute.startsWith(output + '/')))
+                return true;
+            return relative(watchDirectory, absolute)
+                .split(/[\\/]/)
+                .some((part) => [
+                'node_modules',
+                '.git',
+                '.celld',
+                '.wrangler',
+                '.skillshare',
+                'dist',
+                'coverage',
+            ].includes(part));
+        },
+        awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
+    });
+    const ready = once(watcher, 'ready', { signal: options.signal });
+    watcher.on('error', (error) => console.error('File watcher:', error));
+    const fingerprints = new Map();
+    async function fingerprint(path) {
+        try {
+            return createHash('sha256')
+                .update(await readFile(path))
+                .digest('hex');
+        }
+        catch {
+            return '';
+        }
+    }
+    watcher.on('all', async (event, path) => {
+        if (event === 'addDir' || event === 'unlinkDir' || closing)
+            return;
+        const digest = await fingerprint(path);
+        if (closing || fingerprints.get(path) === digest)
+            return;
+        fingerprints.set(path, digest);
+        console.log(`Changed: ${relative(watchDirectory, path)}`);
+        clearTimeout(debounce);
+        debounce = setTimeout(schedule, 150);
+    });
+    let closePromise;
+    function close() {
+        return (closePromise ??= (async () => {
+            closing = true;
+            options.signal?.removeEventListener('abort', onAbort);
+            clearTimeout(debounce);
+            await watcher.close();
+            await stop(build);
+            await stop(node);
+            await work;
+            await proxy.close();
+        })());
+    }
+    const onAbort = () => {
+        void close();
+    };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted) {
+        await close();
+        options.signal.throwIfAborted();
+    }
+    try {
+        await ready;
+        await Promise.all(Object.entries(watcher.getWatched()).flatMap(([directory, names]) => names.map(async (name) => {
+            const path = resolve(directory, name);
+            fingerprints.set(path, await fingerprint(path));
+        })));
+        console.log(`SkillShare Pages development: ${url}\nWatching ${watchDirectory}\nSwitch users using the development toolbar. Ctrl+C to stop.`);
+        schedule();
+        await work;
+        return {
+            url,
+            close,
+            get generation() {
+                return generation;
+            },
+            get error() {
+                return lastError;
+            },
+        };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+export async function runPageDev(directory, flags) {
+    const allowed = new Set([
+        'watch-dir',
+        'build',
+        'slug',
+        'port',
+        'celld',
+        'user-id',
+        'user-name',
+        'user-email',
+    ]);
+    for (const name of Object.keys(flags))
+        if (!allowed.has(name))
+            throw new Error(`Unknown pages dev option --${name}`);
+    const controller = new AbortController();
+    const shutdown = () => controller.abort();
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    try {
+        const development = await startPageDev({
+            directory,
+            watchDirectory: flags['watch-dir'],
+            build: flags.build,
+            slug: flags.slug,
+            port: flags.port ? Number(flags.port) : undefined,
+            celld: flags.celld,
+            userId: flags['user-id'],
+            userName: flags['user-name'],
+            userEmail: flags['user-email'],
+            signal: controller.signal,
+        });
+        if (!controller.signal.aborted)
+            await new Promise((resolve) => controller.signal.addEventListener('abort', () => resolve(), {
+                once: true,
+            }));
+        await development.close();
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            throw error;
+    }
+    finally {
+        process.removeListener('SIGINT', shutdown);
+        process.removeListener('SIGTERM', shutdown);
+    }
+}

package/dist/pages.js

@@ -0,0 +1,51 @@
+import { builtinModules } from 'node:module';
+import { build } from 'esbuild';
+import { parse, printParseErrorCode } from 'jsonc-parser';
+import { resolve, relative } from 'node:path';
+export async function preparePageFiles(directory, files) {
+    const configurations = files.filter(file => file.relativePath === 'wrangler.json' || file.relativePath === 'wrangler.jsonc');
+    if (configurations.length > 1)
+        throw new Error('Publish only one of wrangler.json and wrangler.jsonc.');
+    const configFile = configurations[0];
+    if (!configFile) {
+        if (!files.some(file => file.relativePath === 'index.html'))
+            throw new Error('The page directory must contain index.html or a Wrangler configuration at its root.');
+        return files;
+    }
+    const errors = [];
+    const config = parse(configFile.content.toString('utf8'), errors, { allowTrailingComma: true });
+    if (errors.length || !config || typeof config !== 'object' || Array.isArray(config))
+        throw new Error(`Invalid ${configFile.relativePath}: ${errors.map(error => printParseErrorCode(error.error)).join(', ')}`);
+    if (!config.main || config.no_bundle === true)
+        return files;
+    if (typeof config.main !== 'string' || !files.some(file => file.relativePath === config.main.replace(/^\.\//, '')))
+        throw new Error('Wrangler main must name a file inside the uploaded project.');
+    if (files.some(file => file.relativePath.startsWith('__skillshare/')))
+        throw new Error('The __skillshare directory is reserved for the compiled Worker.');
+    const outputDirectory = resolve(directory, '__skillshare');
+    const output = await build({
+        absWorkingDir: directory,
+        entryPoints: [config.main],
+        outdir: outputDirectory,
+        entryNames: 'worker',
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2024',
+        conditions: ['workerd', 'worker', 'browser'],
+        external: ['cloudflare:*', 'node:*', ...builtinModules],
+        loader: { '.wasm': 'copy' },
+    });
+    config.main = '__skillshare/worker.js';
+    // Native celld still performs its own validation/bundling, including sibling WASM modules.
+    const prepared = files.map(file => file === configFile
+        ? { ...file, content: Buffer.from(JSON.stringify(config, null, 2)) } : file);
+    for (const file of output.outputFiles)
+        prepared.push({
+            relativePath: relative(directory, file.path).replaceAll('\\', '/'),
+            content: Buffer.from(file.contents),
+            contentType: file.path.endsWith('.wasm') ? 'application/wasm' : 'text/javascript; charset=utf-8',
+        });
+    return prepared;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadient/skillshare",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Skillshare CLI for installing and publishing Quadient skills",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "dev": "tsx index.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "start": "node ./dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test pages.test.ts pages-dev.test.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -29,6 +30,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0"
+    "@clack/prompts": "^1.7.0",
+    "chokidar": "4.0.3",
+    "esbuild": "0.28.2",
+    "jsonc-parser": "3.3.1"
   }
 }