stitch2 0.0.0-stage → 0.7.2

package/dist/sandbox.js

@@ -0,0 +1,183 @@
+/**
+ * Sandboxes: isolated folders where fresh agents design from a brief without seeing the project's other
+ * versions, so their work is not anchored to what exists ("fresh eyes"), and where changes to the skills can
+ * be tested on output that only the rules produced.
+ *
+ *   stitch2 sandbox create <dir> <brief.md>… [--device mobile|desktop] [--context <screen>…]
+ *     The project's config, its design folder without screens (DESIGN.md, tokens, components, the catalog and
+ *     templates), the skills from the config, a copy of stitch2 and the briefs (one screen each, named after the
+ *     file). --context adds the approved versions of other screens, to stay consistent with them.
+ *   stitch2 sandbox import <dir> [--label "…"]
+ *     Brings every screen designed there back as the next version of its screen, status review, with a note
+ *     saying where it came from.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, symlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BASE, CONFIG_NAME, config } from './config.js';
+import { listScreens, meta, ROOT, tag, writeMeta } from './screens.js';
+const argv = process.argv.slice(2);
+const sub = argv[0] === 'create' || argv[0] === 'import' ? argv.shift() : 'create';
+const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    if (i < 0)
+        return undefined;
+    const values = [];
+    for (let j = i + 1; j < argv.length && !argv[j].startsWith('--'); j++)
+        values.push(argv[j]);
+    argv.splice(i, values.length + 1);
+    return values;
+};
+const appDir = (c) => c.screenDirs.filter((d) => d !== c.stitchDir).at(-1) ?? 'screens';
+if (sub === 'create') {
+    const device = flag('device')?.[0] ?? 'mobile';
+    const context = flag('context') ?? [];
+    const [dir, ...briefs] = argv;
+    if (!dir || !briefs.length) {
+        console.error('usage: stitch2 sandbox create <dir> <brief.md>… [--device mobile|desktop] [--context <screen>…]');
+        process.exit(1);
+    }
+    const out = resolve(dir);
+    if (existsSync(out) && readdirSync(out).length) {
+        console.error(`${out} is not empty`);
+        process.exit(1);
+    }
+    // The running code (src/*.ts from a checkout, dist/*.js from an install) and the node_modules it resolves from.
+    const code = dirname(fileURLToPath(import.meta.url));
+    const codeDir = basename(code);
+    const ext = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    // stitch2's own dependencies: its node_modules in a checkout or workspace, the folder it sits in when
+    // installed (npm puts dependencies next to it, pnpm in its store folder next to it).
+    let modules = '';
+    for (let d = join(code, '..'); !modules && dirname(d) !== d; d = dirname(d)) {
+        if (existsSync(join(d, 'node_modules', 'yaml')))
+            modules = join(d, 'node_modules');
+        else if (basename(d) === 'node_modules' && existsSync(join(d, 'yaml')))
+            modules = d;
+    }
+    // The design folder minus every screen, except the catalog and templates (files starting with _).
+    const generated = new Set(['renders', 'checks.json', 'type-audit.json', 'consistency']);
+    cpSync(ROOT, join(out, 'design'), {
+        recursive: true,
+        filter: (src) => {
+            const rel = relative(ROOT, src);
+            if (!rel)
+                return true;
+            if (generated.has(rel.split('/')[0]) ||
+                config.sandboxExclude?.some((x) => rel === x || rel.startsWith(`${x}/`)))
+                return false;
+            const screenDir = config.screenDirs.find((d) => rel === d || rel.startsWith(`${d}/`));
+            if (!screenDir || rel === screenDir)
+                return true;
+            if (rel === config.catalogDir ||
+                rel.startsWith(`${config.catalogDir}/`) ||
+                config.catalogDir.startsWith(`${rel}/`))
+                return true;
+            return basename(rel).startsWith('_');
+        },
+    });
+    // Approved versions of the context screens (never of the screens being designed).
+    const designing = new Set(briefs.map((b) => basename(b).replace(/\.md$/, '')));
+    const copied = listScreens().filter((s) => s.status === 'approved' && context.includes(s.screen) && !designing.has(s.screen));
+    for (const s of copied) {
+        mkdirSync(dirname(join(out, 'design', s.path)), { recursive: true });
+        cpSync(join(ROOT, s.path), join(out, 'design', s.path));
+        const assets = join(ROOT, dirname(s.path), 'assets');
+        if (existsSync(assets))
+            cpSync(assets, join(out, 'design', dirname(s.path), 'assets'), { recursive: true });
+    }
+    // Skills are often symlinks into a package; dereference so nothing points back out of the sandbox.
+    for (const s of config.skills)
+        cpSync(resolve(BASE, s), join(out, s), { recursive: true, dereference: true });
+    writeFileSync(join(out, CONFIG_NAME), `${JSON.stringify({ ...config, designDir: 'design', screenDirs: config.screenDirs.filter((d) => d !== config.stitchDir), archiveDirs: [] }, null, 2)}\n`);
+    cpSync(code, join(out, 'stitch2', codeDir), { recursive: true });
+    cpSync(join(code, '..', 'package.json'), join(out, 'stitch2/package.json'));
+    symlinkSync(modules, join(out, 'stitch2/node_modules'));
+    mkdirSync(join(out, 'briefs'), { recursive: true });
+    for (const b of briefs)
+        cpSync(resolve(b), join(out, 'briefs', basename(b)));
+    const p = config.prefix;
+    const target = (name) => `design/${appDir(config)}/${name}/${device}-v1.html`;
+    writeFileSync(join(out, 'AGENTS.md'), `# Design sandbox
+
+This folder is the whole project for this task. Read and write files only inside it; do not open anything
+outside it (no other checkouts, no git history, no web searches for this project's existing screens). Fetching
+public design guides listed in the skills is fine.
+
+- Skills: ${config.skills.map((s) => `${s}/SKILL.md`).join(', ')} (follow their workflow)
+- Design system: design/DESIGN.md, with its generated tokens next to it; components in the catalog,
+  design/${config.catalogDir}${copied.length ? `\n- Approved screens to stay consistent with: ${copied.map((s) => `design/${s.path}`).join(', ')}` : ''}
+- Briefs, one screen each: ${briefs.map((b) => `briefs/${basename(b)} → ${target(basename(b).replace(/\.md$/, ''))}`).join('; ')}.
+  Start from the template in design/${appDir(config)}/; set <meta name="${p}-screen"> to the brief's name,
+  ${p}-device to ${device} and ${p}-status to review when done.
+- stitch2, from this folder: node stitch2/${codeDir}/cli.${ext} check --shots once, then
+  node stitch2/${codeDir}/cli.${ext} check <path> --shots --strict (renders in design/renders/),
+  node stitch2/${codeDir}/cli.${ext} type <path>, node stitch2/${codeDir}/cli.${ext} canvas (PORT=4410)
+`);
+    writeFileSync(join(out, 'sandbox.json'), `${JSON.stringify({ project: BASE, created: new Date().toISOString(), device, briefs: briefs.map((b) => basename(b)), context: copied.map((s) => s.path) }, null, 2)}\n`);
+    console.log(`sandbox ready: ${out} (${briefs.length} brief(s)${copied.length ? `, ${copied.length} approved screen(s) for context` : ''})`);
+    console.log(`  run a fresh agent there (no shared conversation), then: stitch2 sandbox import ${out}`);
+}
+else {
+    const label = flag('label')?.join(' ');
+    const [dir] = argv;
+    if (!dir) {
+        console.error('usage: stitch2 sandbox import <dir> [--label "…"]');
+        process.exit(1);
+    }
+    const box = resolve(dir);
+    const boxConfig = JSON.parse(readFileSync(join(box, CONFIG_NAME), 'utf8'));
+    const boxRoot = join(box, boxConfig.designDir);
+    const files = [];
+    const walk = (d) => {
+        if (!existsSync(d))
+            return;
+        for (const e of readdirSync(d)) {
+            const f = join(d, e);
+            if (statSync(f).isDirectory()) {
+                if (e !== 'assets')
+                    walk(f);
+            }
+            else if (e.endsWith('.html') && !e.startsWith('_'))
+                files.push(f);
+        }
+    };
+    for (const d of boxConfig.screenDirs)
+        walk(join(boxRoot, d));
+    const versions = listScreens();
+    const next = (screen, device) => {
+        const taken = versions
+            .filter((s) => s.screen === screen && s.device === device)
+            .map((s) => Number(/^v(\d+)$/.exec(s.version)?.[1] ?? 1));
+        return Math.max(0, ...taken) + 1;
+    };
+    let imported = 0;
+    for (const f of files) {
+        const rel = relative(boxRoot, f);
+        if (rel.startsWith(`${boxConfig.catalogDir}/`))
+            continue;
+        const html = readFileSync(f, 'utf8');
+        if (meta(html, tag('status')) === 'approved')
+            continue; // context copied in from the project
+        const screen = meta(html, tag('screen')) ?? basename(dirname(f));
+        const device = meta(html, tag('device')) ?? 'mobile';
+        const n = next(screen, device);
+        const path = `${appDir(config)}/${screen}/${device}-v${n}.html`;
+        mkdirSync(dirname(join(ROOT, path)), { recursive: true });
+        cpSync(f, join(ROOT, path));
+        const assets = join(dirname(f), 'assets');
+        if (existsSync(assets))
+            cpSync(assets, join(ROOT, dirname(path), 'assets'), { recursive: true });
+        writeMeta(path, {
+            [tag('screen')]: screen,
+            [tag('device')]: device,
+            [tag('status')]: 'review',
+            [tag('source')]: 'lab',
+            [tag('note')]: `Fresh-eyes version from sandbox ${basename(box)}${label ? ` (${label})` : ''}: designed without seeing the other versions.`,
+        });
+        versions.push({ ...versions[0], screen, device: device, version: `v${n}` });
+        console.log(`  ${screen} ${device} v${n} (${config.designDir}/${path})`);
+        imported++;
+    }
+    console.log(`imported ${imported} screen(s) from ${box}; review them on the canvas`);
+}

package/dist/screens.d.ts

@@ -0,0 +1,34 @@
+import { ROOT } from './config.ts';
+export { ROOT };
+/** A lab meta tag name: <prefix>-screen, <prefix>-status… (the prefix comes from the config). */
+export declare const tag: (name: string) => string;
+export type Status = 'draft' | 'review' | 'approved' | 'archived';
+export declare const STATUSES: Status[];
+export interface Screen {
+    /** Path under design/, e.g. "stitch/home.html" — also the URL path on the lab server. */
+    path: string;
+    /** The folder, e.g. "stitch" or "screens/home". */
+    group: string;
+    /** File name without .html. */
+    name: string;
+    title: string;
+    /** Frame width in px: <meta name="<prefix>-frame-width" content="390">, default 390 (phone). */
+    width: number;
+    mtime: number;
+    /** "screen", or "components" for the component catalog. */
+    kind: 'screen' | 'components';
+    /** Which app screen this file is a version of (<meta name="<prefix>-screen">), e.g. "home". */
+    screen: string;
+    device: 'mobile' | 'desktop';
+    /** Where the version came from: stitch, lab or trial. */
+    source: 'stitch' | 'lab' | 'trial';
+    /** Short version label: "v3", "Stitch", "Trial 2". */
+    version: string;
+    status: Status;
+    /** The reviewer's note (<meta name="<prefix>-note">). */
+    note: string;
+}
+export declare const meta: (html: string, name: string) => string | undefined;
+export declare function listScreens(): Screen[];
+/** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
+export declare function writeMeta(path: string, values: Record<string, string | undefined>): void;

package/dist/screens.js

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { config, ROOT } from './config.js';
+export { ROOT };
+/** A lab meta tag name: <prefix>-screen, <prefix>-status… (the prefix comes from the config). */
+export const tag = (name) => `${config.prefix}-${name}`;
+export const STATUSES = ['draft', 'review', 'approved', 'archived'];
+function* htmlFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.name.startsWith('_') || e.name.startsWith('.') || e.name === 'assets')
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            yield* htmlFiles(p);
+        else if (e.name.endsWith('.html'))
+            yield p;
+    }
+}
+export const meta = (html, name) => new RegExp(`<meta\\s+name="${name}"\\s+content="([^"]*)"`, 'i').exec(html)?.[1];
+export function listScreens() {
+    const out = [];
+    const under = (path, dir) => path.startsWith(`${dir}/`);
+    for (const dir of config.screenDirs) {
+        for (const file of htmlFiles(join(ROOT, dir))) {
+            const html = readFileSync(file, 'utf8');
+            const path = relative(ROOT, file);
+            const name = path
+                .split('/')
+                .pop()
+                .replace(/\.html$/, '');
+            const group = relative(ROOT, join(file, '..'));
+            const width = Number(meta(html, tag('frame-width')) ?? 390);
+            const archive = config.archiveDirs.find((d) => under(path, d));
+            const source = (meta(html, tag('source')) ??
+                (under(path, config.stitchDir) ? 'stitch' : archive ? 'trial' : 'lab'));
+            // design/screens/<screen>/<device>-v<N>.html, or older files named after the screen.
+            const versioned = /^(mobile|desktop)-v(\d+)$/.exec(name);
+            out.push({
+                path,
+                group,
+                name,
+                title: /<title>([^<]*)<\/title>/i.exec(html)?.[1]?.trim() ?? '',
+                width,
+                mtime: statSync(file).mtimeMs,
+                kind: under(path, config.catalogDir) ? 'components' : 'screen',
+                screen: meta(html, tag('screen')) ?? (versioned ? group.split('/').pop() : name),
+                device: (meta(html, tag('device')) ??
+                    (versioned?.[1] || (width >= 768 ? 'desktop' : 'mobile'))),
+                source,
+                version: meta(html, tag('version')) ??
+                    (versioned
+                        ? `v${versioned[2]}`
+                        : source === 'stitch'
+                            ? 'Stitch'
+                            : (archive?.split('/').pop() ?? 'v1')),
+                status: (meta(html, tag('status')) ?? (archive ? 'archived' : 'review')),
+                note: meta(html, tag('note'))?.replaceAll('&quot;', '"').replaceAll('&amp;', '&') ?? '',
+            });
+        }
+    }
+    return out;
+}
+/** Sets (or removes, with undefined) <prefix>-* meta tags in a screen file, keeping the rest of it untouched. */
+export function writeMeta(path, values) {
+    const file = join(ROOT, path);
+    let html = readFileSync(file, 'utf8');
+    for (const [name, value] of Object.entries(values)) {
+        const re = new RegExp(`[ \\t]*<meta\\s+name="${name}"\\s+content="[^"]*"\\s*/?>\\n?`, 'i');
+        html = html.replace(re, '');
+        if (value === undefined || value === '')
+            continue;
+        const tag = `<meta name="${name}" content="${value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('\n', ' ')}" />\n`;
+        html = /<head[^>]*>\n?/i.test(html)
+            ? html.replace(/<head[^>]*>\n?/i, (m) => `${m.endsWith('\n') ? m : `${m}\n`}${tag}`)
+            : tag + html;
+    }
+    writeFileSync(file, html);
+}

package/dist/serve.d.ts

@@ -0,0 +1,4 @@
+export declare function startServer(port: number): Promise<{
+    port: number;
+    close: () => void;
+}>;

package/dist/serve.js

@@ -0,0 +1,181 @@
+/**
+ * The stitch2 server: the canvas at /, DESIGN.md drawn at /design, the screen list at /api/screens
+ * (POST /api/screens/meta sets a version's status or note), check results at /api/checks, live-reload events
+ * at /events, and every file under design/ by its path. Local only (127.0.0.1).
+ * Usage: stitch2 canvas   (PORT=4400 by default)
+ */
+import { existsSync, readFileSync, statSync, watch } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, extname, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILE, config } from './config.js';
+import { designPage } from './design-page.js';
+import { annotate } from './pick.js';
+/**
+ * Inlines <link rel="stylesheet" type="text/tailwindcss" href="…">: the Tailwind v4 browser build reads @theme and
+ * @utility only from inline <style type="text/tailwindcss"> blocks. On one line, so source line numbers hold.
+ */
+function inlineTailwind(html, file) {
+    return html.replace(/<link\b[^>]*\btype="text\/tailwindcss"[^>]*>/g, (tag) => {
+        const href = /\bhref="([^"]+)"/.exec(tag)?.[1];
+        const css = href && (href.startsWith('/') ? join(ROOT, href) : join(dirname(file), href));
+        if (!css || !existsSync(css))
+            return `<!-- stitch2: ${href} not found -->`;
+        return `<style type="text/tailwindcss">${readFileSync(css, 'utf8').replace(/\s*\n\s*/g, ' ')}</style>`;
+    });
+}
+import { listScreens, ROOT, STATUSES, tag, writeMeta } from './screens.js';
+const CANVAS = fileURLToPath(new URL('./canvas.html', import.meta.url));
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.md': 'text/markdown; charset=utf-8',
+};
+export function startServer(port) {
+    const clients = new Set();
+    const changed = new Set();
+    let timer;
+    // Editors write files in bursts; one event per quiet moment is enough.
+    const watcher = watch(ROOT, { recursive: true }, (_event, file) => {
+        if (!file || file.startsWith('renders'))
+            return;
+        changed.add(file.toString());
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            const data = `data: ${JSON.stringify({ paths: [...changed] })}\n\n`;
+            changed.clear();
+            for (const c of clients)
+                c.write(data);
+        }, 150);
+    });
+    const keepAlive = setInterval(() => {
+        for (const c of clients)
+            c.write(': ping\n\n');
+    }, 25_000);
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://lab');
+        const json = (v) => {
+            res.writeHead(200, { 'content-type': TYPES['.json'], 'cache-control': 'no-store' });
+            res.end(JSON.stringify(v));
+        };
+        if (url.pathname === '/') {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end(readFileSync(CANVAS));
+        }
+        if (url.pathname === '/design') {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end(designPage());
+        }
+        if (url.pathname === '/compare/index.html' && !existsSync(join(ROOT, 'compare/index.html'))) {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end('<body style="background:#0f0f11;color:#a1a1aa;font:15px system-ui;padding:32px">No comparison yet: run <code>stitch2 compare</code> with the app running.</body>');
+        }
+        if (url.pathname === '/consistency/index.html' && !existsSync(join(ROOT, 'consistency/index.html'))) {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end('<body style="background:#0f0f11;color:#a1a1aa;font:15px system-ui;padding:32px">No consistency report yet: run <code>stitch2 consistency</code>.</body>');
+        }
+        if (url.pathname === '/api/screens/meta' && req.method === 'POST') {
+            let body = '';
+            req.on('data', (c) => {
+                body += c;
+            });
+            req.on('end', () => {
+                try {
+                    const { path, status, note } = JSON.parse(body);
+                    const all = listScreens();
+                    const target = all.find((s) => s.path === path);
+                    if (!target || (status && !STATUSES.includes(status)))
+                        throw new Error('unknown screen or status');
+                    const values = {};
+                    if (status)
+                        values[tag('status')] = status;
+                    if (note !== undefined)
+                        values[tag('note')] = note.trim() || undefined;
+                    writeMeta(path, values);
+                    // One approved version per screen and device: approving archives the previous one.
+                    if (status === 'approved')
+                        for (const s of all)
+                            if (s.path !== path &&
+                                s.screen === target.screen &&
+                                s.device === target.device &&
+                                s.status === 'approved')
+                                writeMeta(s.path, { [tag('status')]: 'archived' });
+                    json(listScreens());
+                }
+                catch (e) {
+                    res.writeHead(400, { 'content-type': 'text/plain' });
+                    res.end(String(e));
+                }
+            });
+            return;
+        }
+        if (url.pathname === '/api/config')
+            return json(config);
+        if (url.pathname === '/api/screens')
+            return json(listScreens());
+        if (url.pathname === '/api/checks') {
+            const file = join(ROOT, 'checks.json');
+            return json(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { screens: {} });
+        }
+        if (url.pathname === '/events') {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-store',
+                connection: 'keep-alive',
+            });
+            res.write(': connected\n\n');
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        const file = normalize(join(ROOT, decodeURIComponent(url.pathname)));
+        if (!file.startsWith(ROOT) || !existsSync(file) || !statSync(file).isFile()) {
+            res.writeHead(404, { 'content-type': 'text/plain' });
+            return res.end('not found');
+        }
+        res.writeHead(200, {
+            'content-type': TYPES[extname(file)] ?? 'application/octet-stream',
+            'cache-control': 'no-store',
+        });
+        // The canvas loads screens with ?pick: their elements carry source lines for picking.
+        if (extname(file) === '.html') {
+            const html = inlineTailwind(readFileSync(file, 'utf8'), file);
+            res.end(url.searchParams.has('pick') ? annotate(html) : html);
+        }
+        else
+            res.end(readFileSync(file));
+    });
+    return new Promise((resolve) => {
+        // Loopback only, on both IPv4 and IPv6: port forwarders often reach "localhost" as ::1. HOST overrides it
+        // (HOST=0.0.0.0 to open the canvas to the network).
+        const host = process.env.HOST ?? '127.0.0.1';
+        let v6;
+        server.listen(port, host, () => {
+            const address = server.address();
+            const actual = typeof address === 'object' && address ? address.port : port;
+            if (!process.env.HOST) {
+                v6 = createServer((req, res) => server.emit('request', req, res));
+                v6.on('error', () => { }).listen(actual, '::1');
+            }
+            resolve({
+                port: actual,
+                close: () => {
+                    watcher.close();
+                    clearInterval(keepAlive);
+                    for (const c of clients)
+                        c.end();
+                    server.close();
+                    v6?.close();
+                },
+            });
+        });
+    });
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const { port } = await startServer(Number(process.env.PORT ?? 4400));
+    console.log(`${config.name}: http://localhost:${port}  (${CONFIG_FILE ?? 'no stitch2.config.json, defaults'}; screens from ${config.screenDirs.join(', ')})`);
+}

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export {};