docugate 0.1.2 → 0.2.0

package/dist/tour-init.js

@@ -0,0 +1,204 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isMap, isSeq, parseDocument } from 'yaml';
+// `docugate tour init` writes the first tour of an app by asking IBM Bob
+// (through Bob Shell) to read the code. Bob does the reading; this file makes
+// sure the result is safe to keep: Bob works in a mode that can only edit tour
+// files, a tour file the user already has is never changed, and every run
+// reports exactly what was added.
+export const TOUR_DIR = '.docugate/tour';
+export const MODE_SLUG = 'tour-writer';
+const MODES_FILE = '.bob/custom_modes.yaml';
+const RULES_FILE = `.bob/rules-${MODE_SLUG}/01-tour-format.md`;
+export const TOUR_RULES = `# DocuGate tour format
+
+A tour explains the screens of an app to a developer who is new to its code.
+It lives in \`${TOUR_DIR}/\`, one markdown file per screen.
+
+## File
+
+- Name the file after the screen's route: \`/invoices/:id\` becomes
+  \`invoices-id.md\`, \`/\` becomes \`home.md\`.
+- Front matter holds \`route\` (the URL pattern, with \`:param\` segments) and
+  \`title\` (the screen's name).
+- Then one \`##\` section per stop, in the order a person reads the screen.
+
+## Stop
+
+\`\`\`md
+## Total
+target: [data-tour="invoice-total"]
+data: GET /api/invoices/:id → total
+code: frontend/src/screens/InvoiceDetail.tsx
+source: backend/src/billing.ts
+docs: https://example.com/docs/billing
+
+The amount due: the subtotal plus tax, computed by \`totals()\` in the backend.
+\`\`\`
+
+- \`target\`: a CSS selector for the element. Prefer \`[data-tour="..."]\`
+  when the element has one. Otherwise use the most stable selector you can
+  see, and add a line \`suggest: add data-tour="name" in <file>\`.
+- \`data\`: the request the value comes from and the field in the response,
+  as \`METHOD /path → field\`. Leave it out for elements that show no data.
+- \`code\`: the file that renders the element, relative to the repository root.
+- \`source\`: optional. The file where the value is computed or stored, when
+  that is somewhere else, such as a backend service.
+- \`docs\`: optional. A link that explains the concept.
+- Then one or two sentences of plain prose: what the element is and why its
+  value is what it is.
+
+## Rules
+
+- Only claim what the code shows. Every path must exist and every endpoint
+  must appear in the code. If you are not sure where a value comes from,
+  leave \`data\` and \`source\` out rather than guess.
+- Pick the elements a new developer would ask about: numbers, statuses,
+  actions and anything whose meaning is not obvious. Not every element.
+- Never edit, rename or delete a tour file that already exists. Only add
+  files for screens that have none.
+- Change nothing outside \`${TOUR_DIR}/\`.
+`;
+export const MODE = {
+    slug: MODE_SLUG,
+    name: '🧭 Tour Writer',
+    description: 'Writes DocuGate tour files that explain each screen of an app.',
+    roleDefinition: 'You read an application\'s frontend and backend code and write DocuGate tour files: for each screen, which elements matter, what they mean, and where their data really comes from.',
+    whenToUse: 'Use this mode to create or extend the tour in .docugate/tour/.',
+    customInstructions: `Follow the tour format in .bob/rules-${MODE_SLUG}/. Only add files for screens that have none.`,
+    groups: ['read', ['edit', { fileRegex: '\\.docugate/tour/.*\\.md$', description: 'Tour files only' }]],
+};
+export class BobMissingError extends Error {
+}
+/** Bob Shell's headless mode signs in with an API key, not the IDE's IBMid session. */
+export class BobKeyMissingError extends Error {
+}
+const defaultRunBob = (args, cwd) => {
+    const result = spawnSync('bob', args, {
+        cwd,
+        encoding: 'utf8',
+        // `bob` is a .cmd shim on Windows, which only runs through a shell.
+        shell: process.platform === 'win32',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.error && result.error.code === 'ENOENT') {
+        throw new BobMissingError('Bob Shell is not installed.');
+    }
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+};
+/** Adds the Tour Writer mode and its rules to the project, keeping whatever is there. */
+export function ensureTourWriter(root) {
+    const created = [];
+    const modesPath = join(root, MODES_FILE);
+    const doc = existsSync(modesPath) ? parseDocument(readFileSync(modesPath, 'utf8')) : parseDocument('customModes: []\n');
+    let modes = doc.get('customModes');
+    if (!isSeq(modes)) {
+        doc.set('customModes', doc.createNode([]));
+        modes = doc.get('customModes');
+    }
+    const seq = modes;
+    const present = seq.items.some((item) => isMap(item) && item.get('slug') === MODE_SLUG);
+    if (!present) {
+        seq.add(doc.createNode(MODE));
+        mkdirSync(join(root, '.bob'), { recursive: true });
+        writeFileSync(modesPath, doc.toString());
+        created.push(MODES_FILE);
+    }
+    const rulesPath = join(root, RULES_FILE);
+    if (!existsSync(rulesPath)) {
+        mkdirSync(join(root, `.bob/rules-${MODE_SLUG}`), { recursive: true });
+        writeFileSync(rulesPath, TOUR_RULES);
+        created.push(RULES_FILE);
+    }
+    return created;
+}
+function snapshot(root) {
+    const dir = join(root, TOUR_DIR);
+    const files = new Map();
+    if (!existsSync(dir))
+        return files;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.md'))
+            continue;
+        const text = readFileSync(join(dir, name), 'utf8');
+        files.set(name, { text, hash: createHash('sha256').update(text).digest('hex') });
+    }
+    return files;
+}
+export function buildPrompt(existing, inlineRules) {
+    const have = existing.length
+        ? `These screens already have a tour file, so leave them exactly as they are: ${existing.join(', ')}.`
+        : 'There is no tour yet.';
+    return [
+        'Read this repository\'s frontend and backend code and write the DocuGate tour:',
+        `one file in ${TOUR_DIR}/ for every screen of the app that does not have one yet.`,
+        have,
+        inlineRules
+            ? `Follow this format and these rules exactly:\n\n${TOUR_RULES}`
+            : `Follow the format and rules in ${RULES_FILE} exactly.`,
+        'When you are done, list the files you wrote.',
+    ].join('\n');
+}
+function parseBobJson(stdout) {
+    // --format json prints one object when the session ends; take the last line
+    // that parses, in case anything was logged before it.
+    for (const line of stdout.trim().split(/\r?\n/).reverse()) {
+        try {
+            const out = JSON.parse(line);
+            const s = out.stats ?? {};
+            const cost = typeof s.session_costs === 'number' ? s.session_costs : s.session_costs?.total;
+            return {
+                stats: { durationMs: s.duration_ms, cost: typeof cost === 'number' ? cost : undefined, taskId: s.task_id },
+                lastMessage: typeof out.last_message === 'string' ? out.last_message : undefined,
+            };
+        }
+        catch {
+            // not the JSON line
+        }
+    }
+    return {};
+}
+// Windows reports a missing command through cmd.exe rather than as ENOENT.
+const isMissing = (run) => run.status === 127 || run.status === 9009 || /not recognized as an internal or external command|command not found/i.test(run.stderr);
+const looksLikeUnknownMode = (run) => /mode/i.test(run.stderr + run.stdout) && run.status !== 0;
+export function tourInit(root, options = {}) {
+    const runBob = options.runBob ?? defaultRunBob;
+    // Check for Bob before touching the project, so a failed run leaves nothing behind.
+    if (isMissing(runBob(['--version'], root)))
+        throw new BobMissingError('Bob Shell is not installed.');
+    const setup = ensureTourWriter(root);
+    mkdirSync(join(root, TOUR_DIR), { recursive: true });
+    const before = snapshot(root);
+    const common = ['run', '--format', 'json', '--workspace', root, '--max-cost', options.maxCost ?? '3'];
+    if (options.teamId)
+        common.push('--team-id', options.teamId);
+    let mode = MODE_SLUG;
+    let run = runBob([...common, '--mode', MODE_SLUG, buildPrompt([...before.keys()], false)], root);
+    if (looksLikeUnknownMode(run)) {
+        // Bob Shell may not load project modes. Agent mode with the rules in the
+        // prompt does the same job; the snapshot below still protects user files.
+        mode = 'agent';
+        run = runBob([...common, '--mode', 'agent', buildPrompt([...before.keys()], true)], root);
+    }
+    if (run.status !== 0 && /API key is required|BOB_API_KEY/i.test(run.stderr + run.stdout)) {
+        throw new BobKeyMissingError('Bob Shell needs an API key to run on its own.');
+    }
+    if (run.status !== 0) {
+        const detail = (run.stderr || run.stdout).trim().split(/\r?\n/).slice(-5).join('\n');
+        throw new Error(`Bob stopped with exit code ${run.status}.${detail ? `\n${detail}` : ''}`);
+    }
+    // Put back any tour file Bob changed: the user's edits always win.
+    const after = snapshot(root);
+    const restored = [];
+    for (const [name, old] of before) {
+        const now = after.get(name);
+        if (!now || now.hash !== old.hash) {
+            writeFileSync(join(root, TOUR_DIR, name), old.text);
+            restored.push(`${TOUR_DIR}/${name}`);
+        }
+    }
+    const added = [...after.keys()].filter((name) => !before.has(name)).map((name) => `${TOUR_DIR}/${name}`);
+    return { setup, added, restored, mode, ...parseBobJson(run.stdout) };
+}

package/dist/tour-install.js

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// `docugate tour install` inserts a development-only pill loader into the
+// app's HTML or Next.js layout entry point. The snippet is wrapped in comment
+// markers so it can be found and removed again without touching anything else.
+export const DEFAULT_PORT = 4178;
+// Comment markers used as anchors — one pair for HTML files, one for TSX/JSX.
+const HTML_OPEN = '<!-- docugate:pill -->';
+const HTML_CLOSE = '<!-- /docugate:pill -->';
+const JSX_OPEN = '{/* docugate:pill */}';
+const JSX_CLOSE = '{/* /docugate:pill */}';
+/** Candidate paths checked in order. The first one that exists wins. */
+export const CANDIDATES = [
+    'app/layout.tsx',
+    'app/layout.jsx',
+    'src/app/layout.tsx',
+    'src/app/layout.jsx',
+    'pages/_document.tsx',
+    'pages/_document.jsx',
+    'index.html',
+    'frontend/index.html',
+    'client/index.html',
+    'web/index.html',
+    'app/index.html',
+    'public/index.html',
+];
+/** Returns true if any candidate file already contains the pill snippet. */
+export function hasPillSnippet(root) {
+    for (const rel of CANDIDATES) {
+        const abs = join(root, rel);
+        if (!existsSync(abs))
+            continue;
+        const text = readFileSync(abs, 'utf8');
+        if (text.includes(HTML_OPEN) || text.includes(JSX_OPEN))
+            return true;
+    }
+    return false;
+}
+function isJsx(rel) {
+    return rel.endsWith('.tsx') || rel.endsWith('.jsx');
+}
+/** The snippet as lines, without indentation: the file it lands in decides that. */
+function makeSnippet(port, jsx) {
+    const url = `http://localhost:${port}/pill.js`;
+    if (jsx) {
+        return [JSX_OPEN, `{process.env.NODE_ENV === 'development' && <script src="${url}" async />}`, JSX_CLOSE];
+    }
+    return [
+        HTML_OPEN,
+        `<script>if(location.hostname==='localhost'||location.hostname==='127.0.0.1'){` +
+            `var s=document.createElement('script');s.src='${url}';document.head.appendChild(s)}</script>`,
+        HTML_CLOSE,
+    ];
+}
+/**
+ * Inserts the snippet on its own lines just above the closing tag, indented one
+ * step deeper than it and with the file's own line endings, so the diff a
+ * developer reviews is three clean added lines.
+ */
+function insertSnippet(text, lines, jsx) {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    let idx = text.lastIndexOf('</body>');
+    // _document.tsx may close with </html> instead of </body>
+    if (idx === -1 && jsx)
+        idx = text.lastIndexOf('</html>');
+    if (idx === -1) {
+        // Graceful fallback: append to end of file.
+        const end = text.endsWith('\n') ? '' : eol;
+        return text + end + lines.join(eol) + eol;
+    }
+    const lineStart = text.lastIndexOf('\n', idx - 1) + 1;
+    const indent = text.slice(lineStart, idx);
+    if (/^[ \t]*$/.test(indent)) {
+        const block = lines.map((line) => `${indent}  ${line}`).join(eol) + eol;
+        return text.slice(0, lineStart) + block + text.slice(lineStart);
+    }
+    // The tag shares its line with other markup: keep it on that line.
+    return text.slice(0, idx) + lines.join(eol) + eol + text.slice(idx);
+}
+/** Removes the whole marked block, including the lines it sat on. */
+function removeSnippet(text, open, close) {
+    const start = text.indexOf(open);
+    if (start === -1)
+        return text;
+    const end = text.indexOf(close, start);
+    if (end === -1)
+        return text;
+    const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+    const from = /^[ \t]*$/.test(text.slice(lineStart, start)) ? lineStart : start;
+    let to = end + close.length;
+    if (text[to] === '\r')
+        to++;
+    if (text[to] === '\n')
+        to++;
+    return text.slice(0, from) + text.slice(to);
+}
+/**
+ * Installs (or removes) the dev-only pill loader snippet in the app's entry
+ * point. Safe to run multiple times — running it again when the snippet is
+ * already present is a no-op.
+ */
+export function tourInstall(root, options = {}) {
+    const port = options.port ?? DEFAULT_PORT;
+    const remove = options.remove ?? false;
+    for (const rel of CANDIDATES) {
+        const abs = join(root, rel);
+        if (!existsSync(abs))
+            continue;
+        const jsx = isJsx(rel);
+        const open = jsx ? JSX_OPEN : HTML_OPEN;
+        const close = jsx ? JSX_CLOSE : HTML_CLOSE;
+        const original = readFileSync(abs, 'utf8');
+        const hasMarker = original.includes(open);
+        if (remove) {
+            if (!hasMarker)
+                return { target: rel, action: 'already' };
+            const updated = removeSnippet(original, open, close);
+            writeFileSync(abs, updated);
+            return { target: rel, action: 'removed' };
+        }
+        if (hasMarker)
+            return { target: rel, action: 'already' };
+        const snippet = makeSnippet(port, jsx);
+        const updated = insertSnippet(original, snippet, jsx);
+        writeFileSync(abs, updated);
+        return { target: rel, action: 'inserted' };
+    }
+    return { target: null, action: 'none' };
+}
+/** The one-line snippet to paste manually when no entry point was found. */
+export function pillSnippetLine(port) {
+    return `<script>if(location.hostname==='localhost'||location.hostname==='127.0.0.1'){var s=document.createElement('script');s.src='http://localhost:${port}/pill.js';document.head.appendChild(s)}</script>`;
+}

package/dist/tour-server.js

@@ -0,0 +1,225 @@
+import { createServer } from 'node:http';
+import { existsSync, mkdirSync, readFileSync, realpathSync, watch, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTours, matchRoute, parseTourFile, routeToFilename, serializeTourFile } from './tour.js';
+// ---------------------------------------------------------------------------
+// Security helpers
+// ---------------------------------------------------------------------------
+/** Returns true when the host string is localhost or 127.0.0.1 (any port). */
+function isLocalhost(host) {
+    const hostname = host.split(':')[0];
+    return hostname === 'localhost' || hostname === '127.0.0.1';
+}
+/**
+ * Check every request for DNS-rebinding safety:
+ * - The Host header must be localhost or 127.0.0.1.
+ * - If an Origin header is present, it must be a localhost origin.
+ * - If an Origin is absent but a Referer is present, the Referer host must be localhost.
+ * - Requests with neither Origin nor Referer (e.g. curl) are allowed.
+ *
+ * Returns true when the request should be accepted.
+ */
+function isAllowed(req) {
+    const host = req.headers['host'] ?? '';
+    if (host && !isLocalhost(host))
+        return false;
+    const origin = req.headers['origin'];
+    if (origin) {
+        try {
+            return isLocalhost(new URL(origin).hostname);
+        }
+        catch {
+            return false;
+        }
+    }
+    const referer = req.headers['referer'];
+    if (referer) {
+        try {
+            return isLocalhost(new URL(referer).hostname);
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+    res.end(text);
+}
+function sendText(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'text/plain' });
+    res.end(body);
+}
+// ---------------------------------------------------------------------------
+// Route title derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derive a title from a route when no title is provided in the request body.
+ * Takes the last non-param segment and title-cases it.
+ * /invoices/:id → "Invoices", / → "Home"
+ */
+function titleFromRoute(route) {
+    const segments = route.split('/').filter((s) => s && !s.startsWith(':'));
+    if (!segments.length)
+        return 'Home';
+    const last = segments[segments.length - 1];
+    return last.charAt(0).toUpperCase() + last.slice(1);
+}
+// ---------------------------------------------------------------------------
+// Request body reader
+// ---------------------------------------------------------------------------
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+function handleGetTour(req, res, root) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const pathname = url.searchParams.get('path') ?? '/';
+    const tours = loadTours(root);
+    const match = tours.find((t) => matchRoute(t.route, pathname));
+    if (!match) {
+        sendJson(res, 404, { error: 'not found' });
+        return;
+    }
+    sendJson(res, 200, { route: match.route, title: match.title, stops: match.stops });
+}
+function handleGetEvents(req, res, root) {
+    const tourDir = join(root, '.docugate', 'tour');
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+    });
+    // Send a "connected" event immediately so the client knows the stream is live.
+    res.write('data: connected\n\n');
+    let closed = false;
+    let watcher = null;
+    if (existsSync(tourDir)) {
+        // Use realpathSync to resolve any 8.3 short names on Windows, which
+        // would otherwise trigger a libuv assertion in fs-event.c.
+        const watchDir = realpathSync.native(tourDir);
+        watcher = watch(watchDir, () => {
+            if (!closed)
+                res.write('data: change\n\n');
+        });
+    }
+    req.on('close', () => {
+        closed = true;
+        // Defer close to avoid calling watcher.close() from within a watcher
+        // callback, which can cause a libuv assertion on Windows.
+        setImmediate(() => watcher?.close());
+    });
+}
+async function handlePutStop(req, res, root) {
+    let body;
+    try {
+        const text = await readBody(req);
+        body = JSON.parse(text);
+    }
+    catch {
+        sendJson(res, 400, { error: 'invalid JSON body' });
+        return;
+    }
+    const { route, title: bodyTitle, stop } = body;
+    if (!route || !stop) {
+        sendJson(res, 400, { error: 'body must have route and stop' });
+        return;
+    }
+    const tourDir = join(root, '.docugate', 'tour');
+    mkdirSync(tourDir, { recursive: true });
+    // Prefer an existing file whose route matches, so we preserve files that
+    // were named differently from what routeToFilename would derive.
+    const existing = loadTours(root).find((t) => t.route === route);
+    const filename = existing?.file
+        ? existing.file.replace(/^\.docugate\/tour\//, '')
+        : routeToFilename(route);
+    const filepath = join(tourDir, filename);
+    const relPath = `.docugate/tour/${filename}`;
+    let tour;
+    if (existing) {
+        const text = readFileSync(filepath, 'utf8');
+        tour = parseTourFile(text, relPath);
+    }
+    else {
+        tour = {
+            route,
+            title: bodyTitle ?? titleFromRoute(route),
+            stops: [],
+        };
+    }
+    // Upsert: find by target and update, or append.
+    const idx = tour.stops.findIndex((s) => s.target === stop.target);
+    if (idx >= 0) {
+        tour.stops[idx] = stop;
+    }
+    else {
+        tour.stops.push(stop);
+    }
+    writeFileSync(filepath, serializeTourFile(tour));
+    sendJson(res, 200, { ok: true });
+}
+function handleGetPill(res) {
+    // pill/dist/pill.js is resolved relative to this package's root directory.
+    // import.meta.url points at dist/tour-server.js at runtime, so go up one level.
+    const pkgRoot = fileURLToPath(new URL('..', import.meta.url));
+    const pillPath = join(pkgRoot, 'pill', 'dist', 'pill.js');
+    if (!existsSync(pillPath)) {
+        sendText(res, 404, 'pill.js not built yet');
+        return;
+    }
+    const content = readFileSync(pillPath);
+    res.writeHead(200, { 'Content-Type': 'application/javascript' });
+    res.end(content);
+}
+export function startTourServer(root, port) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            if (!isAllowed(req)) {
+                sendText(res, 403, 'Forbidden');
+                return;
+            }
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            const path = url.pathname;
+            if (req.method === 'GET' && path === '/tour') {
+                handleGetTour(req, res, root);
+            }
+            else if (req.method === 'GET' && path === '/events') {
+                handleGetEvents(req, res, root);
+            }
+            else if (req.method === 'PUT' && path === '/stop') {
+                handlePutStop(req, res, root).catch((err) => {
+                    sendJson(res, 500, { error: err.message });
+                });
+            }
+            else if (req.method === 'GET' && path === '/pill.js') {
+                handleGetPill(res);
+            }
+            else {
+                sendText(res, 404, 'Not found');
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            const addr = server.address();
+            const boundPort = addr && typeof addr === 'object' ? addr.port : port;
+            resolve({
+                port: boundPort,
+                close: () => server.close(),
+            });
+        });
+        server.on('error', reject);
+    });
+}