@thedesignagent/mcp 0.2.5 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @thedesignagent/mcp
 
-MCP server for [TheDesignAgent](https://thedesignagent.ai): UX and visual judgment for UI that coding agents build.
+MCP server and CLI for [TheDesignAgent](https://thedesignagent.ai): UX and visual judgment for UI that coding agents build.
 
 Your agent gets a build brief before it builds a screen, and a scored review after: does the screen serve the user's job, does it follow UX heuristics, does it match your design system. Reviews use a real screenshot when the page is running.
 
@@ -32,6 +32,14 @@ Use the hosted server if you only need briefs and UX reviews. Use this package w
 
 Get an API key (it starts with `tda_`) at [thedesignagent.ai/dashboard/api-keys](https://thedesignagent.ai/dashboard/api-keys).
 
+You can put the key in each client's config as shown below, or save it once for every client and the CLI:
+
+```
+npx -y --package=@thedesignagent/mcp thedesignagent login
+```
+
+That writes `~/.thedesignagent/credentials`, readable only by you. `THEDESIGNAGENT_API_KEY` still wins when it's set, so you can then leave the `env` lines out of the configs below.
+
 ### Claude Code (recommended: the plugin)
 
 The plugin includes this server, plus skills that teach the agent the brief → build → review loop and `/tda:brief` and `/tda:review` commands:
@@ -105,6 +113,134 @@ The package has two commands, so pass `--package` and name `thedesignagent-mcp`
 
 After the first successful `Discover`, write `{ "project_id": "<id>" }` to `.thedesignagent` and commit it, so every agent on the repo shares the same project context.
 
+## Command line and CI
+
+The same package has a `thedesignagent` command for terminals, headless agent runs and CI. `npx thedesignagent` runs it with no install.
+
+```
+npx thedesignagent check http://localhost:3000/checkout --threshold 7
+npx thedesignagent check app/checkout/page.tsx --checks ux
+npx thedesignagent brief "Build the forecast approval queue"
+```
+
+| Command | What it does |
+| --- | --- |
+| `check [url\|file]` | With no target, checks every page listed in `.thedesignagent` (below). Otherwise scores a page from a screenshot (`visual`) or a source file (`ux`). On a URL, `--checks visual,ux --code <file>` runs both (the UX review reads the page's source). `--task` says what the screen is for. |
+| `brief "<task>"` | Writes a build brief to `.thedesignagent-brief.md` (`--out -` prints it). Point any agent at it from AGENTS.md or CLAUDE.md. |
+| `login [key]` | Saves your API key. Reads it from stdin when piped. |
+
+`check` options: `--threshold <n>` exits 1 when a check's overall score is below `n`; `--json` prints the full result (scores, findings, recommendations, screenshot path) for scripts and agents.
+
+Exit codes: `0` ok, `1` below threshold, `2` error (key, network, usage), `3` the page redirected to a login screen (no review ran, nothing charged).
+
+Both commands find the project from `.thedesignagent` in the repo, or `--project <id>`, or `THEDESIGNAGENT_PROJECT_ID`. Commit `.thedesignagent`: CI clones often use a different remote URL than your machine, so the fallback (a hash of the remote URL) can point at a different project. A project's first brief needs a project model, which your coding agent builds on its first `Discover` call; after that the CLI's briefs work anywhere.
+
+### Checking a set of pages
+
+List the pages to check in `.thedesignagent`, and `check` with no target checks them all:
+
+```json
+{
+  "project_id": "proj_...",
+  "check": {
+    "base_url": "http://localhost:3000",
+    "threshold": 7,
+    "pages": [
+      { "path": "/checkout", "task": "Pay for the items in the cart" },
+      { "path": "/orders", "code": "app/orders/page.tsx", "checks": ["visual", "ux"], "threshold": 7.5 }
+    ]
+  }
+}
+```
+
+```
+npx thedesignagent check
+npx thedesignagent check --base-url https://my-app-git-feature.vercel.app
+```
+
+`--base-url` (or `THEDESIGNAGENT_BASE_URL`) points the same pages at a preview deploy. A page's own `threshold` overrides the shared one, and `--threshold` overrides both. `code` paths are relative to the repo root. The run exits 1 if any page is below its threshold, and 3 if a page redirected to login.
+
+### Only the pages a branch changed
+
+`check --changed` diffs the branch against `origin/main` (in GitHub Actions, the pull request's base branch; `--base <ref>` to choose) and checks the Next.js App Router pages it touched. A changed file counts toward the nearest `page.tsx` above it, so editing `app/orders/_components/table.tsx` re-checks `/orders`. Route groups like `(shop)` are handled. Dynamic routes (`[id]`) have no URL to visit, so list a concrete page for them in `.thedesignagent` (with `code` pointing at the page file) and it's checked when that file changes.
+
+```
+npx thedesignagent check --changed --base-url https://my-app-git-feature.vercel.app --threshold 7
+```
+
+### Headless agent runs
+
+Ask the agent to run the check and fix what it finds:
+
+```
+claude -p "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+codex exec "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+grok -p "Build the checkout page. Then run 'npx thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
+```
+
+Or have the agent write the brief first: `npx thedesignagent brief "Build the checkout page" && claude -p "Read .thedesignagent-brief.md, then build the checkout page."`
+
+### GitHub Actions
+
+Fail a build when a page scores below 7. Add your key as the repository secret `THEDESIGNAGENT_API_KEY`. GitHub's Ubuntu runners include Chrome.
+
+```yaml
+name: Design check
+on: pull_request
+
+jobs:
+  design-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - run: npm start &
+      - run: npx -y wait-on -t 120000 http://localhost:3000/checkout
+      - run: npx -y thedesignagent check http://localhost:3000/checkout --threshold 7
+        env:
+          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}
+```
+
+#### On pull requests: changed pages only, with a PR comment
+
+Check only the pages the pull request touched and post the scores as one comment, updated on every push:
+
+```yaml
+name: Design check
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  design-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - run: npm start &
+      - run: npx -y wait-on -t 120000 http://localhost:3000
+      - run: npx -y thedesignagent check --changed --base-url http://localhost:3000 --threshold 7 --pr-comment
+        env:
+          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+`fetch-depth: 0` lets `--changed` diff against the base branch. The comment lists each page's scores against the threshold, with the top findings and fixes folded under each. If commenting fails (for example without `pull-requests: write`), the check still runs and still sets the exit code.
+
+The score table and the critical and high findings appear on the run's summary page. For pages behind login, set `THEDESIGNAGENT_AUTH_SEED` to an AuthSeed object, `{ "cookies": [...] }` (the format `thedesignagent-auth` saves under `~/.thedesignagent/auth/`), ideally for a test account.
+
 ## Screenshots
 
 `Visual` screenshots `render_url` with your local Chrome, Edge, Brave or Chromium. If it can't find one, set `CHROME_PATH` to the browser binary.
@@ -113,19 +249,35 @@ Screenshots are saved to `~/.thedesignagent/screenshots/` for 24 hours, so you c
 
 ### Pages behind login
 
-Capture a logged-in session once per app:
+When `Visual` lands on a login page it stops before reviewing (nothing is charged) and tells your agent how to save a session. Sessions are stored per site under `~/.thedesignagent/auth/` (readable only by you) and applied to every later screenshot of that site.
+
+There are two ways to save one:
+
+**A login recipe (automatic).** A small script in your repo, `.thedesignagent-login.mjs`, prints either a URL that logs in when opened (a magic link, a dev-only login route) or cookies as JSON. Pipe it into `login`:
 
 ```
-npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000
+node .thedesignagent-login.mjs | npx -y --package=@thedesignagent/mcp thedesignagent-auth login http://localhost:3000/dashboard
 ```
 
-A browser opens; log in, then press Enter (or close the browser). The session is saved under `~/.thedesignagent/auth/` and reused for that origin. When `Visual` hits a login redirect, it tells the agent to ask you to run this command.
+It logs in headlessly, checks the page no longer redirects to login, and saves. The Claude Code plugin's `/tda:setup` writes a recipe for Supabase apps.
+
+**Capture by hand.** Opens a browser window; log in and it saves and closes by itself once you leave the login page:
+
+```
+npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000/dashboard
+```
+
+It uses a dedicated browser profile, so later re-captures are often instant. Agents can run it in the background: it ends with `TDA_AUTH_SAVED <origin>` or `TDA_AUTH_FAILED <reason>`, and gives up after 10 minutes.
+
+Check what's saved with `thedesignagent-auth status <url>`.
 
 ## Environment variables
 
 | Variable | Required | Purpose |
 | --- | --- | --- |
-| `THEDESIGNAGENT_API_KEY` | Yes | Your `tda_` API key |
+| `THEDESIGNAGENT_API_KEY` | Yes, unless you ran `thedesignagent login` | Your `tda_` API key |
+| `THEDESIGNAGENT_PROJECT_ID` | No | Project for the CLI when there's no `.thedesignagent` file |
+| `THEDESIGNAGENT_AUTH_SEED` | No | Session cookies as JSON, for screenshots behind login in CI |
 | `CHROME_PATH` | No | Browser binary for screenshots, if it isn't found automatically |
 | `ANTHROPIC_API_KEY` | No | Enables a fallback review through Claude when TheDesignAgent's API is unreachable |
 

package/dist/auth-capture.js

@@ -1,10 +1,40 @@
 #!/usr/bin/env node
+/**
+ * thedesignagent-auth: save a logged-in session so `Visual` can screenshot
+ * pages behind login.
+ *
+ *   capture <app-url>   Opens a browser window; log in. Saves and closes on its own
+ *                       once you leave the login page (or press Enter / close it).
+ *                       Safe to run from an agent in the background.
+ *   login <app-url>     Non-interactive. Reads a login recipe's output on stdin:
+ *                       either a URL that logs in when opened (a magic link, a
+ *                       dev-only login route) or an AuthSeed JSON ({ cookies, ... }).
+ *                       Logs in headlessly, verifies, saves.
+ *   status <app-url>    Says whether a session is saved and when it expires.
+ *
+ * Every run ends with one machine-readable line for agents:
+ *   TDA_AUTH_SAVED <origin>   |   TDA_AUTH_FAILED <reason>   |   TDA_AUTH_STATUS ...
+ */
 import { findChromeExecutable, isLoginUrl } from './screenshot.js';
-import { saveStoredAuth } from './auth-store.js';
+import { authFilePath, loadStoredAuth, saveStoredAuth, BROWSER_PROFILE_DIR } from './auth-store.js';
+import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline';
+const CAPTURE_TIMEOUT_MS = Number(process.env.TDA_CAPTURE_TIMEOUT_MS ?? 10 * 60 * 1000);
+const POLL_MS = 1500;
 function printUsage() {
-    console.error('Usage: thedesignagent-auth capture <url>');
-    console.error('Example: thedesignagent-auth capture http://localhost:3000');
+    console.error('Usage:');
+    console.error('  thedesignagent-auth capture <app-url>   log in by hand in a browser window');
+    console.error('  thedesignagent-auth login <app-url>     log in from a recipe (URL or AuthSeed JSON on stdin)');
+    console.error('  thedesignagent-auth status <app-url>    show whether a session is saved');
+    console.error('Example: node .thedesignagent-login.mjs | thedesignagent-auth login http://localhost:3000');
+}
+function fail(reason, detail) {
+    console.error('');
+    console.error(`✗ ${reason}`);
+    for (const line of detail ?? [])
+        console.error(`  ${line}`);
+    console.log(`TDA_AUTH_FAILED ${reason}`);
+    process.exit(1);
 }
 async function snapshotSession(browser, page, hostname) {
     try {
@@ -19,144 +49,249 @@ async function snapshotSession(browser, page, hostname) {
             httpOnly: c.httpOnly,
             secure: c.secure,
             sameSite: (c.sameSite === 'Strict' || c.sameSite === 'Lax' || c.sameSite === 'None') ? c.sameSite : undefined,
+            ...(c.expires > 0 && { expires: c.expires }),
         }));
+        // Storage is unreadable on error pages (opaque origin): keep the cookies anyway.
         const storage = await page.evaluate(() => ({
             localStorage: Object.fromEntries(Object.keys(localStorage).map(k => [k, localStorage.getItem(k) ?? ''])),
             sessionStorage: Object.fromEntries(Object.keys(sessionStorage).map(k => [k, sessionStorage.getItem(k) ?? ''])),
-        }));
-        return {
-            cookies,
-            localStorage: storage.localStorage,
-            sessionStorage: storage.sessionStorage,
-            finalUrl: page.url(),
-        };
+        })).catch(() => ({ localStorage: {}, sessionStorage: {} }));
+        return { cookies, localStorage: storage.localStorage, sessionStorage: storage.sessionStorage, finalUrl: page.url() };
     }
     catch {
         return null;
     }
 }
-function waitForEnter() {
-    return new Promise(resolve => {
-        if (!process.stdin.isTTY) {
-            // No TTY (e.g. backgrounded by an agent) — never resolves. Browser-close will trigger instead.
-            return;
-        }
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.once('line', () => { rl.close(); resolve('enter'); });
-    });
-}
-function waitForBrowserClose(browser) {
-    return new Promise(resolve => {
-        browser.on('disconnected', () => resolve('closed'));
-    });
-}
-// Post-trigger verification: if the browser is still alive after Enter was
-// pressed, navigate back to the original URL and re-snapshot. Catches "user
-// pressed Enter too early" — the partial session would otherwise be saved
-// silently and fail on every subsequent visual call.
-async function verifyAndSnapshot(browser, page, url, trigger, fallback) {
-    if (trigger !== 'enter' || !browser.connected)
-        return fallback;
+// Navigate back to the app URL and re-snapshot, so a session is only saved
+// once the app itself accepts it (catches "confirmed before login finished").
+async function verifySnapshot(browser, page, url) {
     try {
-        console.log('Verifying session…');
-        await page.goto(url.href, { waitUntil: 'networkidle0', timeout: 15000 });
-        const snap = await snapshotSession(browser, page, url.hostname);
-        return snap ?? fallback;
+        await page.goto(url.href, { waitUntil: 'networkidle2', timeout: 20000 });
+        return await snapshotSession(browser, page, url.hostname);
     }
     catch {
-        return fallback;
+        return null;
     }
 }
-async function main() {
-    const [, , subcommand, urlArg] = process.argv;
-    if (subcommand !== 'capture' || !urlArg) {
-        printUsage();
-        process.exit(1);
-    }
-    let url;
-    try {
-        url = new URL(urlArg);
-    }
-    catch {
-        console.error(`Invalid URL: ${urlArg}`);
-        process.exit(1);
+function saveSnapshot(url, snap, how) {
+    if (isLoginUrl(snap.finalUrl)) {
+        fail('session not accepted', [
+            `Opening ${url.href} still redirected to a login page: ${snap.finalUrl}`,
+            'Login may not have finished (a second factor or enrolment step still pending?).',
+        ]);
     }
+    const seed = {
+        cookies: snap.cookies,
+        ...(Object.keys(snap.localStorage).length && { localStorage: snap.localStorage }),
+        ...(Object.keys(snap.sessionStorage).length && { sessionStorage: snap.sessionStorage }),
+    };
+    const savedPath = saveStoredAuth(url.href, seed);
+    console.log('');
+    console.log(`✓ Logged in (${how}); ${snap.cookies.length} cookies, ${Object.keys(snap.localStorage).length} localStorage entries`);
+    console.log(`✓ Saved to ${savedPath}. Visual now uses it for every page on ${url.origin}.`);
+    console.log(`TDA_AUTH_SAVED ${url.origin}`);
+    process.exit(0);
+}
+async function launch(opts) {
     const chromePath = findChromeExecutable();
-    if (!chromePath) {
-        console.error('Chrome/Chromium not found. Install Google Chrome (or set CHROME_PATH).');
-        process.exit(1);
-    }
+    if (!chromePath)
+        fail('no browser found', ['Install Google Chrome (or Edge, Brave, Chromium), or set CHROME_PATH.']);
     const puppeteer = (await import('puppeteer-core')).default;
-    console.log(`▌TheDesignAgent▐ auth capture`);
-    console.log(`Opening ${url.href} in a browser window…`);
-    const browser = await puppeteer.launch({
+    return puppeteer.launch({
         executablePath: chromePath,
-        headless: false,
+        headless: opts.headless,
         defaultViewport: { width: 1440, height: 900 },
+        // A dedicated profile keeps "remember me" and SSO sessions between
+        // captures, so re-capturing after expiry is often instant.
+        ...(opts.persistent && { userDataDir: BROWSER_PROFILE_DIR }),
         args: ['--no-sandbox', '--disable-setuid-sandbox'],
     });
+}
+// ── capture ──────────────────────────────────────────────────────────────────
+function waitForEnter() {
+    return new Promise(resolve => {
+        if (!process.stdin.isTTY)
+            return; // backgrounded by an agent: rely on auto-detect / close
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.once('line', () => { rl.close(); resolve('enter'); });
+    });
+}
+async function capture(url) {
+    const hadSavedSession = existsSync(authFilePath(url.href));
+    const browser = await launch({ headless: process.env.TDA_CAPTURE_HEADLESS === '1', persistent: true });
     const [page] = await browser.pages();
-    await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: 30000 });
-    // Continuously snapshot the session as the user navigates, so we always have
-    // a recent capture even if the browser is closed before they confirm.
+    await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => { });
+    console.log('▌TheDesignAgent▐ login capture');
+    console.log(`→ A browser window opened at ${url.href}. Log in to your app there.`);
+    console.log('→ It saves and closes by itself once you reach a logged-in page.');
+    if (process.stdin.isTTY)
+        console.log('  (Or press Enter here, or close the window, when you are done.)');
+    console.log('');
+    // Logged in = we saw a login page on this origin and have now left it (the
+    // page is back on the app, off any login path) for two polls in a row.
+    // If the dedicated profile was already logged in and the app loads straight
+    // away, that counts too when a session was saved before (a re-capture).
+    let sawLogin = isLoginUrl(page.url());
+    let stableOffLogin = 0;
+    const detected = new Promise(resolve => {
+        const timer = setInterval(() => {
+            let current;
+            try {
+                current = new URL(page.url());
+            }
+            catch {
+                return;
+            }
+            const onApp = current.origin === url.origin;
+            if (onApp && isLoginUrl(current.href)) {
+                sawLogin = true;
+                stableOffLogin = 0;
+                return;
+            }
+            if (onApp && (sawLogin || hadSavedSession))
+                stableOffLogin++;
+            else
+                stableOffLogin = 0;
+            if (stableOffLogin >= 2) {
+                clearInterval(timer);
+                resolve('detected');
+            }
+        }, POLL_MS);
+        browser.on('disconnected', () => clearInterval(timer));
+    });
     let lastSnapshot = null;
-    const pollInterval = setInterval(async () => {
+    const snapTimer = setInterval(async () => {
         const snap = await snapshotSession(browser, page, url.hostname);
         if (snap)
             lastSnapshot = snap;
-    }, 2000);
-    const interactiveHint = process.stdin.isTTY
-        ? '→ When you\'re logged in, press Enter in your terminal OR close the browser window.'
-        : '→ When you\'re logged in, close the browser window. (No TTY detected.)';
-    console.log('');
-    console.log('→ Log in to your app in the browser window that just opened.');
-    console.log(interactiveHint);
-    console.log('');
-    const trigger = await Promise.race([waitForEnter(), waitForBrowserClose(browser)]);
-    clearInterval(pollInterval);
-    const verifiedSnapshot = await verifyAndSnapshot(browser, page, url, trigger, lastSnapshot);
-    if (trigger !== 'closed') {
+    }, POLL_MS);
+    const closed = new Promise(resolve => browser.on('disconnected', () => resolve('closed')));
+    const timedOut = new Promise(resolve => setTimeout(() => resolve('timeout'), CAPTURE_TIMEOUT_MS).unref());
+    const trigger = await Promise.race([detected, waitForEnter(), closed, timedOut]);
+    clearInterval(snapTimer);
+    if (trigger === 'timeout') {
         try {
             await browser.close();
         }
-        catch { /* already closing */ }
+        catch { }
+        fail('timed out waiting for login', [`No login completed within ${Math.round(CAPTURE_TIMEOUT_MS / 60000)} minutes. Run it again when ready.`]);
     }
-    if (!verifiedSnapshot) {
-        console.error('');
-        console.error('✗ No session captured — browser may have closed before login completed.');
-        console.error('  Re-run the command and log in before closing the window.');
-        process.exit(1);
+    const snap = trigger === 'closed' ? lastSnapshot : (await verifySnapshot(browser, page, url)) ?? lastSnapshot;
+    try {
+        await browser.close();
+    }
+    catch { }
+    if (!snap)
+        fail('no session captured', ['The window closed before a logged-in page loaded. Run it again.']);
+    saveSnapshot(url, snap, trigger === 'detected' ? 'detected automatically' : trigger === 'enter' ? 'Enter pressed' : 'window closed');
+}
+// ── login (from a recipe) ────────────────────────────────────────────────────
+// Stream stdin: readFileSync(0) throws EAGAIN on a pipe whose writer hasn't
+// finished yet (e.g. a recipe still waiting on a network call).
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+async function login(url) {
+    if (process.stdin.isTTY)
+        fail('nothing on stdin', ['Pipe a login recipe into this command, e.g. node .thedesignagent-login.mjs | thedesignagent-auth login ' + url.origin]);
+    const input = (await readStdin()).trim();
+    if (!input)
+        fail('empty input', ['The login recipe printed nothing.']);
+    let seed = null;
+    let loginUrl = null;
+    if (input.startsWith('{')) {
+        try {
+            seed = JSON.parse(input);
+        }
+        catch {
+            fail('recipe output is not valid JSON');
+        }
+    }
+    else {
+        loginUrl = input.split('\n')[0].trim();
+        try {
+            new URL(loginUrl);
+        }
+        catch {
+            fail('recipe output is neither a URL nor JSON');
+        }
     }
-    if (isLoginUrl(verifiedSnapshot.finalUrl)) {
-        console.error('');
-        console.error('✗ Session not saved — after capture, navigating to the target URL still');
-        console.error('  redirected to a login page. This usually means:');
-        console.error('  • Login was not fully completed (2FA still pending? form not submitted?)');
-        console.error('  • You confirmed before reaching a logged-in page');
-        console.error('');
-        console.error(`  Final URL after verification: ${verifiedSnapshot.finalUrl}`);
-        console.error('');
-        console.error('  Re-run the command. Make sure you reach a logged-in page in the');
-        console.error('  browser before pressing Enter or closing the window.');
+    const browser = await launch({ headless: true, persistent: false });
+    try {
+        const page = await browser.newPage();
+        if (seed?.cookies?.length) {
+            await page.browserContext().setCookie(...seed.cookies.map(c => ({ ...c, domain: c.domain ?? url.hostname, path: c.path ?? '/' })));
+        }
+        if (seed?.localStorage || seed?.sessionStorage) {
+            await page.evaluateOnNewDocument((ls, ss) => {
+                try {
+                    for (const [k, v] of ls)
+                        localStorage.setItem(k, v);
+                    for (const [k, v] of ss)
+                        sessionStorage.setItem(k, v);
+                }
+                catch { }
+            }, Object.entries(seed.localStorage ?? {}), Object.entries(seed.sessionStorage ?? {}));
+        }
+        if (loginUrl) {
+            await page.goto(loginUrl, { waitUntil: 'networkidle2', timeout: 30000 }).catch(() => { });
+        }
+        const snap = await verifySnapshot(browser, page, url);
+        await browser.close();
+        if (!snap)
+            fail('could not load the app', [`Is the dev server running at ${url.origin}?`]);
+        saveSnapshot(url, snap, loginUrl ? 'login URL' : 'recipe cookies');
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch { }
+    }
+}
+// ── status ───────────────────────────────────────────────────────────────────
+function status(url) {
+    const seed = loadStoredAuth(url.href);
+    if (!seed) {
+        console.log(`No saved session for ${url.origin}.`);
+        console.log(`TDA_AUTH_STATUS none ${url.origin}`);
+        return;
+    }
+    const expiries = (seed.cookies ?? []).map(c => c.expires).filter((e) => typeof e === 'number' && e > 0);
+    if (!expiries.length) {
+        console.log(`Session saved for ${url.origin} (session cookies, no expiry recorded).`);
+        console.log(`TDA_AUTH_STATUS saved ${url.origin}`);
+        return;
+    }
+    const soonest = new Date(Math.min(...expiries) * 1000);
+    const expired = soonest.getTime() < Date.now();
+    console.log(`Session saved for ${url.origin}; ${expired ? 'expired' : 'expires'} ${soonest.toISOString()}.`);
+    console.log(`TDA_AUTH_STATUS ${expired ? 'expired' : 'saved'} ${url.origin} ${soonest.toISOString()}`);
+}
+// ── main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const [, , subcommand, urlArg] = process.argv;
+    if (!subcommand || !urlArg || !['capture', 'login', 'status'].includes(subcommand)) {
+        printUsage();
         process.exit(1);
     }
-    const seed = {
-        cookies: verifiedSnapshot.cookies,
-        ...(Object.keys(verifiedSnapshot.localStorage).length && { localStorage: verifiedSnapshot.localStorage }),
-        ...(Object.keys(verifiedSnapshot.sessionStorage).length && { sessionStorage: verifiedSnapshot.sessionStorage }),
-    };
-    const savedPath = saveStoredAuth(url.href, seed);
-    console.log('');
-    console.log(`✓ Trigger: ${trigger === 'closed' ? 'browser closed' : 'Enter pressed'}`);
-    console.log(`✓ Captured ${verifiedSnapshot.cookies.length} cookies, ${Object.keys(verifiedSnapshot.localStorage).length} localStorage entries, ${Object.keys(verifiedSnapshot.sessionStorage).length} sessionStorage entries`);
-    console.log(`✓ Final URL: ${verifiedSnapshot.finalUrl}`);
-    console.log(`✓ Saved to: ${savedPath}`);
-    console.log('');
-    console.log(`▌TheDesignAgent▐ will now auto-apply this session for any URL on ${url.origin}.`);
-    console.log(`To re-capture (after expiry or logout), run this command again.`);
-    process.exit(0);
+    let url;
+    try {
+        url = new URL(urlArg);
+    }
+    catch {
+        fail(`invalid URL: ${urlArg}`);
+    }
+    if (subcommand === 'status')
+        return status(url);
+    if (subcommand === 'login')
+        return login(url);
+    return capture(url);
 }
-main().catch(err => {
-    console.error('auth-capture failed:', err instanceof Error ? err.message : err);
-    process.exit(1);
-});
+main().catch(err => fail('auth command crashed', [err instanceof Error ? err.message : String(err)]));

package/dist/auth-store.d.ts

@@ -1,5 +1,6 @@
 import type { AuthSeed } from './screenshot.js';
 export declare const AUTH_STORE_DIR: string;
+export declare const BROWSER_PROFILE_DIR: string;
 export declare function authFilePath(url: string): string;
 export declare function loadStoredAuth(url: string): AuthSeed | null;
 export declare function saveStoredAuth(url: string, seed: AuthSeed): string;

package/dist/auth-store.js

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+// Saved sessions are live login cookies: keep them readable by the owner only.
 export const AUTH_STORE_DIR = join(homedir(), '.thedesignagent', 'auth');
+export const BROWSER_PROFILE_DIR = join(homedir(), '.thedesignagent', 'browser-profile');
 function safeFilename(origin) {
     return origin.replace(/^https?:\/\//, '').replace(/[^a-z0-9.-]/gi, '_') + '.json';
 }
@@ -20,8 +22,10 @@ export function loadStoredAuth(url) {
     }
 }
 export function saveStoredAuth(url, seed) {
-    mkdirSync(AUTH_STORE_DIR, { recursive: true });
+    mkdirSync(AUTH_STORE_DIR, { recursive: true, mode: 0o700 });
+    chmodSync(AUTH_STORE_DIR, 0o700);
     const path = authFilePath(url);
-    writeFileSync(path, JSON.stringify(seed, null, 2));
+    writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
+    chmodSync(path, 0o600);
     return path;
 }

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};