waygraph 0.13.7 → 0.15.0

package/assets/stubs/stub.pdf

@@ -0,0 +1,32 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>
+endobj
+4 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+5 0 obj
+<< /Length 44 >>
+stream
+BT /F1 18 Tf 20 100 Td (waygraph stub) Tj ET
+endstream
+endobj
+xref
+0 6
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+0000000241 00000 n 
+0000000311 00000 n 
+trailer
+<< /Size 6 /Root 1 0 R >>
+startxref
+405
+%%EOF

package/dist/agent-dive.d.ts

@@ -10,6 +10,15 @@ export interface AgentSpec {
 /** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
 export declare function parseAgentSpec(filePath: string): AgentSpec;
 export declare function loadAgentSpecs(): AgentSpec[];
+/**
+ * Claude Code Skills (`.claude/skills/<name>/SKILL.md`) - a different
+ * mechanism than the agent persona files above: loadable instructions
+ * triggered by task shape, not a persona. Claude-Code-specific (no
+ * equivalent in the opencode/cursor/vscode loops), additive to the
+ * `claude` loop only. Reuses the same `name: .../description: ...` +
+ * body frontmatter shape `parseAgentSpec` already parses.
+ */
+export declare function loadSkillSpecs(): AgentSpec[];
 export interface AgentDiveOptions {
     loop: AgentDiveLoop;
     projectDir: string;

package/dist/agent-dive.js

@@ -12,6 +12,9 @@ function packageRoot() {
 function agentsTemplateDir() {
     return join(packageRoot(), "templates", "agents");
 }
+function skillsTemplateDir() {
+    return join(packageRoot(), "templates", "skills");
+}
 /** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
 export function parseAgentSpec(filePath) {
     const raw = readFileSync(filePath, "utf-8");
@@ -65,6 +68,23 @@ export function loadAgentSpecs() {
         .sort()
         .map((f) => parseAgentSpec(join(dir, f)));
 }
+/**
+ * Claude Code Skills (`.claude/skills/<name>/SKILL.md`) - a different
+ * mechanism than the agent persona files above: loadable instructions
+ * triggered by task shape, not a persona. Claude-Code-specific (no
+ * equivalent in the opencode/cursor/vscode loops), additive to the
+ * `claude` loop only. Reuses the same `name: .../description: ...` +
+ * body frontmatter shape `parseAgentSpec` already parses.
+ */
+export function loadSkillSpecs() {
+    const dir = skillsTemplateDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".skill.md"))
+        .sort()
+        .map((f) => parseAgentSpec(join(dir, f)));
+}
 function writeFileLogged(path, content, kind) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content.endsWith("\n") ? content : content + "\n");
@@ -104,6 +124,10 @@ ${agent.instructions}
 function vscodeAgentMd(agent) {
     return claudeAgentMd(agent);
 }
+function claudeSkillMd(skill) {
+    const lines = ["---", `name: ${skill.name}`, `description: ${skill.description}`, "---", "", skill.instructions, ""];
+    return lines.join("\n");
+}
 export function runAgentDive(opts) {
     const agents = loadAgentSpecs();
     const root = opts.projectDir;
@@ -116,6 +140,14 @@ export function runAgentDive(opts) {
             for (const a of agents) {
                 writeFileLogged(join(dir, `${a.name}.md`), claudeAgentMd(a), "claude agent");
             }
+            const skills = loadSkillSpecs();
+            if (skills.length > 0) {
+                console.log(`  ${skills.length} skill(s) from package templates`);
+                const skillsRoot = join(root, ".claude", "skills");
+                for (const s of skills) {
+                    writeFileLogged(join(skillsRoot, s.name, "SKILL.md"), claudeSkillMd(s), "claude skill");
+                }
+            }
             break;
         }
         case "opencode": {

package/dist/auto-explore-run.d.ts

@@ -1,3 +1,7 @@
+import type { Page, BrowserContext } from "@playwright/test";
+import { Engine, MemPage } from "./index.js";
+import { type BlockEntry } from "./auto-explore.js";
+import type { Checkpoint } from "./types.js";
 export interface AutoExploreOptions {
     /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
     cli?: boolean;
@@ -7,11 +11,25 @@ export interface AutoExploreOptions {
     /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
     blocksSelect?: import("./blocks-select.js").BlocksSelect;
 }
+export declare function resolveBaseUrl(projectDir: string): string | undefined;
+export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
+export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
 /**
- * Saucedemo-only defaults. Exact key names only — never substring `"login"`
- * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`.
+ * A consumer's own `key<string>("login-email")` must stay unset here, or it
+ * silently gets a saucedemo credentials object instead of its own default.
  */
 export declare function defaultMemValueForKey(keyName: string): unknown | undefined;
+/** Pre-seed known demo keys (saucedemo creds) so headful/cli do not stop for mem forms. */
+export declare function seedDefaultMem(library: Map<string, BlockEntry>, mem: MemPage): void;
+export declare function ensureMem(entry: BlockEntry, mem: MemPage, cli: boolean): Promise<void>;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage, headful: boolean): Promise<Checkpoint<string>>;
+export type PickResult = {
+    type: "pick";
+    index: number;
+} | {
+    type: "quit";
+};
 /**
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */

package/dist/auto-explore-run.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { Engine, start, end, locate, MemPage } from "./index.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
-function resolveBaseUrl(projectDir) {
+export function resolveBaseUrl(projectDir) {
     const pkgPath = join(projectDir, "package.json");
     if (existsSync(pkgPath)) {
         try {
@@ -55,14 +55,14 @@ async function inferCheckpointFromUrl(page) {
     }
     return null;
 }
-async function detectHere(page, navBlocks) {
+export async function detectHere(page, navBlocks) {
     const fromUrl = await inferCheckpointFromUrl(page);
     if (fromUrl)
         return fromUrl;
     const tags = navBlocks.map((n) => n.block);
     return locate(page, tags, { timeoutMs: 1500 });
 }
-async function ensureLivePage(context, page, startUrl) {
+export async function ensureLivePage(context, page, startUrl) {
     if (!page.isClosed())
         return page;
     const fresh = await context.newPage();
@@ -78,8 +78,9 @@ function missingMemKeys(entry, mem) {
 }
 const DEFAULT_CREDENTIALS = { username: "standard_user", password: "secret_sauce" };
 /**
- * Saucedemo-only defaults. Exact key names only — never substring `"login"`
- * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`.
+ * A consumer's own `key<string>("login-email")` must stay unset here, or it
+ * silently gets a saucedemo credentials object instead of its own default.
  */
 export function defaultMemValueForKey(keyName) {
     if (keyName === "login-credentials" ||
@@ -112,7 +113,7 @@ function seedMemFromEnv(mem, entry) {
     }
 }
 /** Pre-seed known demo keys (saucedemo creds) so headful/cli do not stop for mem forms. */
-function seedDefaultMem(library, mem) {
+export function seedDefaultMem(library, mem) {
     const raw = process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     let envParsed = {};
     if (raw) {
@@ -151,7 +152,7 @@ async function promptMemCli(entry, mem) {
         rl.close();
     }
 }
-async function ensureMem(entry, mem, cli) {
+export async function ensureMem(entry, mem, cli) {
     if (missingMemKeys(entry, mem).length === 0)
         return;
     if (seedMemFromEnv(mem, entry))
@@ -193,7 +194,7 @@ async function setAutoPanelRunning(page, label) {
     }, label)
         .catch(() => { });
 }
-async function runOneBlock(engine, entry, context, page, mem, headful) {
+export async function runOneBlock(engine, entry, context, page, mem, headful) {
     const navClick = entry.block.__waygraphNavClick;
     if (entry.kind === "nav" && navClick !== undefined) {
         await page

package/dist/auto-explore.js

@@ -1,4 +1,4 @@
-import { readdirSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { discoverGraph } from "./graph.js";
 function walkDir(dir, pattern) {
@@ -23,8 +23,28 @@ function walkDir(dir, pattern) {
     }
     return results;
 }
+/**
+ * Real, confirmed bug this fixes: a bare `import(url.href)` is permanently
+ * cached by Node's ESM loader for the lifetime of the process, keyed on the
+ * exact specifier. `AutoSession.reloadLibrary()` exists specifically so a
+ * Block edited on disk mid-session takes effect without restarting the
+ * session - but a SECOND `reload` of a file already imported once in this
+ * process silently kept returning the FIRST version's content, no matter
+ * how many times the file changed on disk after that. A one-shot CLI
+ * process (`waygraph graph`, etc.) never hits this - it only ever imports
+ * each file once anyway - but a long-running `--detach` session calling
+ * `reloadLibrary()` repeatedly does.
+ *
+ * Fix: bust the cache with the file's own mtime as a query param - a
+ * genuinely changed file gets a new specifier (forcing a fresh import); an
+ * UNCHANGED file between two reloads keeps hitting the SAME specifier (no
+ * unbounded accumulation of dead module instances across many reloads).
+ */
 async function importModule(filePath) {
-    const url = new URL(`file://${resolve(filePath)}`);
+    const resolved = resolve(filePath);
+    const url = new URL(`file://${resolved}`);
+    const mtimeMs = statSync(resolved).mtimeMs;
+    url.searchParams.set("t", String(mtimeMs));
     return (await import(url.href));
 }
 function isBlockLike(val) {

package/dist/auto-session-ipc.d.ts

@@ -0,0 +1,123 @@
+import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "./auto-session.js";
+export interface SessionMeta {
+    sessionId: string;
+    socketPath: string;
+    pid: number;
+    projectDir: string;
+    startedAt: string;
+    headless: boolean;
+}
+export type StatusOrSendResponse = {
+    ok: true;
+    snapshot: SessionSnapshot;
+    quit: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export type DomResponse = {
+    ok: true;
+    snapshot: DomSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export type TraceResponse = {
+    ok: true;
+    trace: TraceStep[];
+} | {
+    ok: false;
+    error: string;
+};
+export type ConsoleResponse = {
+    ok: true;
+    consoleLog: ConsoleLogEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+export type StorageResponse = ({
+    ok: true;
+} & StorageSnapshot) | {
+    ok: false;
+    error: string;
+};
+export type ReachResponse = ApplyPathResult;
+/**
+ * Client-side: sends one request to a running session and returns its
+ * response. Reports a stale/unreachable session as an error within
+ * `timeoutMs`, never hangs indefinitely.
+ */
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "status";
+} | {
+    op: "send";
+    pick: string;
+} | {
+    op: "click";
+    selector: string;
+} | {
+    op: "type";
+    selector: string;
+    text: string;
+} | {
+    op: "press";
+    selector: string;
+    key: string;
+} | {
+    op: "goto";
+    url: string;
+} | {
+    op: "reload";
+} | {
+    op: "resync";
+} | {
+    op: "upload";
+    selector: string;
+    stub: StubFileKind | {
+        filePath: string;
+    };
+}, timeoutMs?: number): Promise<StatusOrSendResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "dom";
+} & InspectDomOptions, timeoutMs?: number): Promise<DomResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "trace";
+}, timeoutMs?: number): Promise<TraceResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "console";
+}, timeoutMs?: number): Promise<ConsoleResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "storage";
+}, timeoutMs?: number): Promise<StorageResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "reach";
+    checkpoint: string;
+}, timeoutMs?: number): Promise<ReachResponse>;
+/**
+ * Server-side: runs `session` behind a unix socket at
+ * `.waygraph-auto/<sessionId>.sock`, writing session metadata only once the
+ * socket is actually listening (the metadata file's existence is the
+ * "session is ready" signal a spawning parent polls for). Requests are
+ * processed one at a time via a queue - Node's single-threaded event loop
+ * already prevents true parallelism, but two overlapping `await`-heavy
+ * handlers could still interleave against the same page/mem.
+ */
+export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean): Promise<void>;
+/** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
+export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
+/**
+ * Parent-side: spawns a detached background process running the same
+ * explore session as a socket server, waits for it to signal readiness (its
+ * metadata file appearing), and returns its identity. Recurses through the
+ * existing `bin/waygraph` launcher (same tsx/esm registration every other
+ * invocation already gets) with the hidden `__auto-serve` command, rather
+ * than re-implementing that resolution here.
+ */
+export declare function spawnDetachedSession(init: AutoSessionInit, readyTimeoutMs?: number): Promise<SessionMeta>;
+/**
+ * Client-only interactive loop against a running detached session - reopens
+ * the same rendering/parsing the foreground `--cli` loop uses, driven purely
+ * through `status`/`send`. No server-side support beyond those two ops.
+ */
+export declare function runAttachLoop(projectDir: string, sessionId: string): Promise<void>;