leglas 0.2.0 → 0.3.0

package/dist/index.js

@@ -45,7 +45,7 @@ function parseNew(rest) {
   if (surface === void 0) {
     return {
       kind: "error",
-      message: "leglas new needs a surface name, for example: leglas new hero"
+      message: "leglas new needs a surface name, for example: npx leglas new hero"
     };
   }
   return { kind: "new", surface, print, json, from };
@@ -128,7 +128,7 @@ function parseClassify(rest) {
   if (changes.length === 0) {
     return {
       kind: "error",
-      message: "leglas classify needs what the direction will touch, for example: leglas classify --change package.json --rewrite src/theme.css"
+      message: "leglas classify needs what the direction will touch, for example: npx leglas classify --change package.json --rewrite src/theme.css"
     };
   }
   return { kind: "classify", changes, json };
@@ -203,7 +203,7 @@ function parseArgs(argv) {
     if (title === void 0) {
       return {
         kind: "error",
-        message: 'leglas keep needs a direction title, for example: leglas keep "Aurora" --to src/components/hero.tsx'
+        message: 'leglas keep needs a direction title, for example: npx leglas keep "Aurora" --to src/components/hero.tsx'
       };
     }
     if (to === void 0) {
@@ -253,7 +253,7 @@ function parseArgs(argv) {
     if (surface === void 0) {
       return {
         kind: "error",
-        message: "leglas explore needs a surface name, for example: leglas explore hero --count 6"
+        message: "leglas explore needs a surface name, for example: npx leglas explore hero --count 6"
       };
     }
     return { kind: "explore", surface, count, basedOn, json };
@@ -294,7 +294,7 @@ function parseArgs(argv) {
     if (title === void 0) {
       return {
         kind: "error",
-        message: 'leglas show needs a direction title, for example: leglas show "Aurora" --json'
+        message: 'leglas show needs a direction title, for example: npx leglas show "Aurora" --json'
       };
     }
     return { kind: "show", title, json };
@@ -556,8 +556,8 @@ The set exists to be chosen from, and the choice only means something if the dir
 One trap, seen every time this goes wrong: a set collapses toward whichever direction is built first. Decide all ${count} before building any, and if two would read as the same direction at a glance, replace one of them.` : `Build ${count} variations of the "${basedOn}" direction for "${surface}".
 
 The set exists to pick a variant of a direction already chosen, so every variation must stay recognisably that direction. The trap here is drift: change enough and the comparison stops being about the variant. Vary each one deliberately and hold everything else still; if a variation grows into a new direction, it belongs in its own exploration instead.`;
-  const register = basedOn === null ? `  leglas add --title "<name>" --url "/?v-${slug}=<key>" --note "<the idea, one line>"` : `  leglas add --title "<name>" --url "/?v-${slug}=<key>" --based-on ${JSON.stringify(basedOn)} --note "<the idea, one line>"`;
-  const mechanics = `Each one is its own file under .leglas/variants/${slug}/, listed in the DIRECTIONS map in that folder's switch file. If there is no switch file yet, run \`leglas new ${slug}\` first. Register each one the moment it renders, not the set at the end. The interface picks a registration up within seconds, so whoever asked watches the set fill in:
+  const register = basedOn === null ? `  npx leglas add --title "<name>" --url "/?v-${slug}=<key>" --note "<the idea, one line>"` : `  npx leglas add --title "<name>" --url "/?v-${slug}=<key>" --based-on ${JSON.stringify(basedOn)} --note "<the idea, one line>"`;
+  const mechanics = `Each one is its own file under .leglas/variants/${slug}/, listed in the DIRECTIONS map in that folder's switch file. If there is no switch file yet, run \`npx leglas new ${slug}\` first. Register each one the moment it renders, not the set at the end. The interface picks a registration up within seconds, so whoever asked watches the set fill in:
 
 ${register}
 
@@ -609,46 +609,48 @@ When asked for design variations, alternatives, or "a few options":
    If a direction cannot be additive, because it must change dependencies,
    change build configuration, or rewrite an existing file's behaviour, ask
    where it should live before writing it:
-   \`leglas classify --change package.json --rewrite src/theme.css --json\`.
+   \`npx leglas classify --change package.json --rewrite src/theme.css --json\`.
    When the answer is \`checkout\`, build the direction on its own git branch
-   and register it with \`leglas add --title "\u2026" --url "/" --branch <branch>\`
+   and register it with \`npx leglas add --title "\u2026" --url "/" --branch <branch>\`
    (the config needs \`devCommand\` with \`{port}\`). Everything below is the
    ordinary, in-app path.
-2. Run \`leglas explore <surface> --count <n>\` first, adding
+2. Run \`npx leglas explore <surface> --count <n>\` first, adding
    \`--based-on "<title>"\` when the user wants variations of a direction they
    already like. It prints what the set needs and how to register it. In
    short: new directions must genuinely disagree with each other, variants of
    one must not, and either way decide the whole set before building any of
    it. The designs themselves are yours.
 3. If the surface has no switcher yet, run
-   \`leglas new <surface> --from <the component that renders it today>\`. It
+   \`npx leglas new <surface> --from <the component that renders it today>\`. It
    writes one under \`.leglas/variants/<surface>/\` and prints the single line
    to add where that surface renders. \`--from\` makes the baseline re-export
    the real component rather than copying it, so it stays live.
-4. Before building, make sure the interface is up. If \`leglas\` is not
-   already running, tell the user to run it, and hand them the URL now
-   rather than when the set is done: the rail picks up each registration
-   within seconds, so they get to watch the exploration fill in.
+4. Before building, make sure the interface is up. If Leglas is not
+   already running, tell the user to run \`npx leglas\`, and hand them the
+   URL now rather than when the set is done: the rail picks up each
+   registration within seconds, so they get to watch the exploration fill in.
 5. Build one direction at a time: its own file beside the others in
    \`.leglas/variants/<surface>/\`, listed in the \`DIRECTIONS\` map in that
    folder's \`switch\` file, then registered the moment it renders:
-   \`leglas add --title "Aurora" --url "/?v-<surface>=aurora" --note "One line on the idea."\`
+   \`npx leglas add --title "Aurora" --url "/?v-<surface>=aurora" --note "One line on the idea."\`
    Register each direction as it lands, never the whole set at the end. To
    the user watching the rail, a batch at the end is minutes of nothing and
    then everything at once.
 
-When the user asks to change one direction, check \`leglas requests --json\`
+When the user asks to change one direction, check \`npx leglas requests --json\`
 first: they may have described it from the interface, and the request names the
-exact file. Clear the queue with \`leglas requests --clear\` once done.
+exact file. Acknowledge them with \`npx leglas requests --clear\` once done: it
+drops what you collected and reports anything the user typed while you worked,
+which is yours to collect and do next.
 
 If the user wants requests handled the moment they are typed, without relaying
-each one, tell them about \`leglas watch --run "claude -p {prompt}"\` (any
+each one, tell them about \`npx leglas watch --run "claude -p {prompt}"\` (any
 agent command works; {prompt} receives the request). It runs in their
 terminal, hands each request to that command as it arrives, and the interface
 shows the request's progress.
 
 When the user picks a winner, run
-\`leglas keep "<title>" --to <path in real source>\`. It moves that direction
+\`npx leglas keep "<title>" --to <path in real source>\`. It moves that direction
 out of the ignored directory, deletes the rest of the exploration, and drops
 them from the rail. Then change their component to use the kept component
 instead of the switcher.
@@ -659,14 +661,14 @@ Useful to know:
   ships. Move a direction into real source only when it wins.
 - If the project has no running app yet, a direction can be a plain HTML
   file: write it under \`.leglas/pages/\` and register it with
-  \`leglas add --title "Aurora" --file .leglas/pages/aurora.html\`. Leglas
+  \`npx leglas add --title "Aurora" --file .leglas/pages/aurora.html\`. Leglas
   serves the file itself, so no dev server is needed. Sibling assets in the
   same directory resolve normally.
 - Titles identify previews and must be unique. The user may rename one in the
   rail, which renames it on their machine only; the commands answer to either
   name, so use whichever they said.
-- \`leglas list\` shows every direction, shared and local.
-- \`leglas show "<title>" --json\` answers for one of them: the file behind it,
+- \`npx leglas list\` shows every direction, shared and local.
+- \`npx leglas show "<title>" --json\` answers for one of them: the file behind it,
   the variants based on it, what it is being compared against, and anything
   they have asked for that is not done yet. Run it when handed a direction you
   did not register yourself.
@@ -676,7 +678,7 @@ Useful to know:
 ${AGENTS_MARKER_END}
 `;
 var STARTER_CONFIG = `// Previews are URLs of your own app. Add one per direction you want to
-// compare, then run \`leglas\`.
+// compare, then run \`npx leglas\`.
 export default {
   // Where your dev server is. Override at the command line with --user-port.
   devServer: "http://localhost:3000",
@@ -880,12 +882,12 @@ function isExplorationFile(path) {
 }
 var CHECKOUT_STEPS = [
   "Build the direction on its own branch: git switch -c <branch>, commit it there, switch back.",
-  'Register it: leglas add --title "<title>" --url "/" --branch <branch>.',
+  'Register it: npx leglas add --title "<title>" --url "/" --branch <branch>.',
   "Make sure the config sets devCommand (with {port}), so Leglas can start the checkout."
 ];
 var IN_APP_STEPS = [
   "Author it additively under .leglas/variants/<surface>/, beside the existing directions.",
-  'Register it: leglas add --title "<title>" --url "/?v-<surface>=<direction>".'
+  'Register it: npx leglas add --title "<title>" --url "/?v-<surface>=<direction>".'
 ];
 function classifyDirection(input) {
   const checkout = (reason) => ({ level: "checkout", reason, steps: CHECKOUT_STEPS });
@@ -1341,7 +1343,12 @@ async function removeRequest(cwd, id) {
   return true;
 }
 async function clearRequests(cwd) {
-  await writeQueue(cwd, []);
+  const requests = await readRequests(cwd);
+  const pending = requests.filter((request) => request.status !== "picked-up");
+  const cleared = requests.length - pending.length;
+  if (cleared > 0)
+    await writeQueue(cwd, pending);
+  return { cleared, pending: pending.length };
 }
 
 // ../server/dist/renames.js
@@ -1380,7 +1387,7 @@ function resolveTitle(input, titles, renames) {
 import { createReadStream, existsSync as existsSync2, statSync } from "fs";
 import http2 from "http";
 import net3 from "net";
-import { extname, join as join6, normalize } from "path";
+import { extname, join as join6, normalize, relative as relative2 } from "path";
 var LEGLAS_PREFIX = "/leglas";
 var DEFAULT_PORT = 4100;
 var PORT_ATTEMPTS = 20;
@@ -1432,8 +1439,8 @@ function probe(target, timeoutMs = 1e3) {
   });
 }
 function serveFrom(res, dir, relativePath) {
-  const relative3 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
-  const candidate = join6(dir, relative3);
+  const relative4 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
+  const candidate = join6(dir, relative4);
   if (!candidate.startsWith(dir))
     return false;
   if (!existsSync2(candidate) || !statSync(candidate).isFile())
@@ -1446,9 +1453,36 @@ function serveFrom(res, dir, relativePath) {
   return true;
 }
 function serveShellFile(res, shellDir, urlPath) {
-  const relative3 = normalize(urlPath.slice(LEGLAS_PREFIX.length)).replace(/^(\.\.[/\\])+/, "");
-  const isRoot = relative3 === "" || relative3 === "." || relative3 === "/";
-  return serveFrom(res, shellDir, isRoot ? "index.html" : relative3);
+  const relative4 = normalize(urlPath.slice(LEGLAS_PREFIX.length)).replace(/^(\.\.[/\\])+/, "");
+  const isRoot = relative4 === "" || relative4 === "." || relative4 === "/";
+  return serveFrom(res, shellDir, isRoot ? "index.html" : relative4);
+}
+function snapshotConfig(cwd) {
+  const path = findConfigFile(cwd);
+  if (path === null)
+    return null;
+  try {
+    return { path, mtimeMs: statSync(path).mtimeMs };
+  } catch {
+    return null;
+  }
+}
+function configStalenessNotice(cwd, boot, current) {
+  if (boot === null && current === null)
+    return null;
+  if (boot === null && current !== null) {
+    const label = relative2(cwd, current.path) || current.path;
+    return `${label} appeared after Leglas started. Restart leglas to pick it up.`;
+  }
+  if (boot !== null && current === null) {
+    const label = relative2(cwd, boot.path) || boot.path;
+    return `${label} was removed after Leglas started. Restart leglas to run without it.`;
+  }
+  if (boot !== null && current !== null && (boot.path !== current.path || boot.mtimeMs !== current.mtimeMs)) {
+    const label = relative2(cwd, current.path) || current.path;
+    return `${label} changed after Leglas started. Restart leglas to pick it up.`;
+  }
+  return null;
 }
 var PLACEHOLDER = `<!doctype html>
 <meta charset="utf-8">
@@ -1494,12 +1528,17 @@ async function startServer(options) {
   const { config, configErrors = [], shellDir = null, project = "", cwd = process.cwd(), fileMounts = /* @__PURE__ */ new Map() } = options;
   const target = config?.devServer ?? "http://localhost:3000";
   const proxy = createProxyHandler({ target });
+  const bootConfigSnapshot = snapshotConfig(cwd);
   let lastSeen = null;
   const server = http2.createServer((req, res) => {
     const url = req.url ?? "/";
     const path = url.split("?")[0] ?? "/";
     if (path === `${LEGLAS_PREFIX}/api/config`) {
       const boot = config?.previews ?? [];
+      const errors = [...configErrors];
+      const notice = configStalenessNotice(cwd, bootConfigSnapshot, snapshotConfig(cwd));
+      if (notice !== null)
+        errors.push(notice);
       return void readLocalPreviews(cwd).then(({ previews: local }) => {
         const known = new Set(boot.map((preview) => preview.title));
         const fresh = local.filter((preview) => !known.has(preview.title) && preview.branch === void 0 && preview.file === void 0);
@@ -1507,13 +1546,13 @@ async function startServer(options) {
           project,
           devServer: target,
           previews: [...boot, ...fresh],
-          errors: configErrors
+          errors
         });
       }).catch(() => sendJson(res, 200, {
         project,
         devServer: target,
         previews: boot,
-        errors: configErrors
+        errors
       }));
     }
     if (path === `${LEGLAS_PREFIX}/api/request` && req.method === "POST") {
@@ -1587,21 +1626,28 @@ async function startServer(options) {
       const rest = path.slice(FILES_PREFIX.length + 1);
       const slash = rest.indexOf("/");
       const slug = slash === -1 ? rest : rest.slice(0, slash);
-      let relative3 = slash === -1 ? "" : rest.slice(slash + 1);
+      let relative4 = slash === -1 ? "" : rest.slice(slash + 1);
       try {
-        relative3 = decodeURIComponent(relative3);
+        relative4 = decodeURIComponent(relative4);
       } catch {
-        relative3 = "";
+        relative4 = "";
       }
       const dir = fileMounts.get(slug);
-      if (dir !== void 0 && relative3 !== "" && serveFrom(res, dir, relative3))
+      if (dir !== void 0 && relative4 !== "" && serveFrom(res, dir, relative4))
         return;
       res.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
       return res.end("Leglas: no such preview file.");
     }
+    if (path.startsWith(`${LEGLAS_PREFIX}/api/`)) {
+      return sendJson(res, 404, { error: "No such Leglas API path." });
+    }
     if (path === LEGLAS_PREFIX || path.startsWith(`${LEGLAS_PREFIX}/`)) {
       if (shellDir !== null && serveShellFile(res, shellDir, path))
         return;
+      if (shellDir !== null) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+        return res.end("Leglas: no such path.");
+      }
       res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
       return res.end(PLACEHOLDER);
     }
@@ -1650,7 +1696,7 @@ function planKeep(options) {
   if (!winner) {
     return {
       ok: false,
-      error: `No direction called ${JSON.stringify(options.title)}. Run leglas list to see them.`
+      error: `No direction called ${JSON.stringify(options.title)}. Run npx leglas list to see them.`
     };
   }
   const from = targetFor(winner.url);
@@ -1745,7 +1791,7 @@ function resolveOrExplain(input, titles, renames) {
   }
   return {
     ok: false,
-    error: `No direction called ${JSON.stringify(input)}. Renaming one in the rail only renames it here, and it still answers to its title in the config, which its reference block quotes. leglas list shows every title.`
+    error: `No direction called ${JSON.stringify(input)}. Renaming one in the rail only renames it here, and it still answers to its title in the config, which its reference block quotes. npx leglas list shows every title.`
   };
 }
 
@@ -1895,7 +1941,7 @@ async function runNew(options, deps) {
   deps.log("Then register them so they appear in the interface:");
   deps.log("");
   for (const preview of plan.previews) {
-    deps.log(`  leglas add --title ${JSON.stringify(preview.title)} --url ${JSON.stringify(preview.url)}`);
+    deps.log(`  npx leglas add --title ${JSON.stringify(preview.title)} --url ${JSON.stringify(preview.url)}`);
   }
   return { exitCode: 0, written };
 }
@@ -1924,7 +1970,7 @@ async function runAdd(options, deps) {
     const local = await readLocalPreviews(options.cwd);
     const titles = new Set([...shared, ...local.previews].map((preview) => preview.title));
     if (!titles.has(options.preview.basedOn)) {
-      const error = `--based-on names ${JSON.stringify(options.preview.basedOn)}, which is not a registered direction. leglas list shows what exists.`;
+      const error = `--based-on names ${JSON.stringify(options.preview.basedOn)}, which is not a registered direction. npx leglas list shows what exists.`;
       if (options.json) envelope(deps, false, { error });
       else deps.error(error);
       return { exitCode: 1 };
@@ -1957,6 +2003,7 @@ async function runAdd(options, deps) {
       local: true,
       ...options.preview.branch === void 0 ? {} : { branch: options.preview.branch },
       ...options.preview.file === void 0 ? {} : { file: options.preview.file },
+      note: options.preview.branch === void 0 && options.preview.file === void 0 ? "A running interface picks this up within seconds." : "Restart Leglas to see this preview: branch checkouts and file mounts are built when Leglas starts.",
       ...needsDevCommand ? { warning: "The config sets no devCommand, so Leglas cannot start this branch yet. Add devCommand (with {port}) to the config." } : {}
     });
   } else {
@@ -1972,7 +2019,7 @@ async function runAdd(options, deps) {
     if (options.preview.branch === void 0 && options.preview.file === void 0) {
       deps.log("Local to this machine. A running interface picks it up within seconds.");
     } else {
-      deps.log("Local to this machine. Restart Leglas to see it, or run leglas list.");
+      deps.log("Local to this machine. Restart Leglas to see it, or run npx leglas list.");
     }
   }
   return { exitCode: 0 };
@@ -2007,7 +2054,7 @@ async function runList(options, deps) {
     return { exitCode: errors.length === 0 ? 0 : 1 };
   }
   if (previews.length === 0) {
-    deps.log("No previews yet. Add one with leglas add, or list them in leglas.config.ts.");
+    deps.log("No previews yet. Add one with npx leglas add, or list them in leglas.config.ts.");
   } else {
     const width = Math.max(...previews.map((preview) => preview.title.length));
     for (const preview of previews) {
@@ -2022,9 +2069,16 @@ async function runList(options, deps) {
 }
 async function runRequests(options, deps) {
   if (options.clear) {
-    await clearRequests(options.cwd);
-    if (options.json) envelope(deps, true, { cleared: true });
-    else deps.log("Queue cleared.");
+    const { cleared, pending } = await clearRequests(options.cwd);
+    if (options.json) envelope(deps, true, { cleared, pending });
+    else {
+      deps.log(cleared === 1 ? "Cleared 1 request." : `Cleared ${cleared} requests.`);
+      if (pending > 0) {
+        deps.log(
+          `${pending} arrived while you worked. Run npx leglas requests to collect ${pending === 1 ? "it" : "them"}.`
+        );
+      }
+    }
     return { exitCode: 0 };
   }
   const requests = await collectRequests(options.cwd);
@@ -2041,7 +2095,7 @@ async function runRequests(options, deps) {
     if (request.target !== null) deps.log(`    ${request.target}`);
   }
   deps.log("");
-  deps.log("Run leglas requests --json to get the full prompts, then --clear when done.");
+  deps.log("Run npx leglas requests --json to get the full prompts, then --clear when done.");
   return { exitCode: 0 };
 }
 
@@ -2067,7 +2121,7 @@ function planShow({ title, previews, requests }) {
   if (!found) {
     return {
       ok: false,
-      error: `No direction called ${JSON.stringify(title)}. Run leglas list to see them.`
+      error: `No direction called ${JSON.stringify(title)}. Run npx leglas list to see them.`
     };
   }
   const variants = previews.filter((preview) => preview.basedOn === title).map(describe);
@@ -2146,7 +2200,7 @@ async function runShow(options, deps) {
     deps.log(`  Pending, not yet done (${plan.requests.length}):`);
     for (const request of plan.requests) deps.log(`    ${request.status}  ${request.intent}`);
     deps.log("");
-    deps.log("  Run leglas requests --json for the full prompts.");
+    deps.log("  Run npx leglas requests --json for the full prompts.");
   }
   return { exitCode: 0 };
 }
@@ -2154,7 +2208,7 @@ async function runShow(options, deps) {
 // src/watch.ts
 var WATCH_PATH = ".leglas/watch.json";
 var PROMPT_TOKEN = "{prompt}";
-var EXAMPLE = `leglas watch --run "claude -p ${PROMPT_TOKEN}"`;
+var EXAMPLE = `npx leglas watch --run "claude -p ${PROMPT_TOKEN}"`;
 function tokenize(template) {
   const tokens = [];
   let current = "";
@@ -2269,7 +2323,7 @@ async function runWatch(options, deps) {
   const raw = options.run ?? saved;
   if (raw === null) {
     deps.error(
-      'Watch needs an agent command the first time: leglas watch --run "claude -p {prompt}"'
+      'Watch needs an agent command the first time: npx leglas watch --run "claude -p {prompt}"'
     );
     return { exitCode: 1 };
   }
@@ -2388,7 +2442,7 @@ async function runClassify(options, deps) {
 // src/run.ts
 import { existsSync as existsSync5 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname8, join as join13, relative as relative2 } from "path";
+import { basename as basename3, dirname as dirname8, join as join13, relative as relative3 } from "path";
 import { fileURLToPath } from "url";
 function findShellDir() {
   const bundled = join13(dirname8(fileURLToPath(import.meta.url)), "shell");
@@ -2501,7 +2555,7 @@ async function run2(options, deps) {
       })
     );
   } else {
-    const configLabel = loaded.path === null ? "no config file, previewing the app root" : relative2(options.cwd, loaded.path) || loaded.path;
+    const configLabel = loaded.path === null ? "no config file, previewing the app root" : relative3(options.cwd, loaded.path) || loaded.path;
     deps.log(`Leglas   ${url}`);
     deps.log(
       `app      ${devServer}${app !== null ? "  (started by Leglas)" : health.reachable ? "" : "  (not reachable)"}`