explorbot 0.2.2 → 0.2.3

package/src/global-config.ts

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import { join } from 'node:path';
+
+const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
+const SITE_DIRS = ['knowledge', 'experience', 'output'];
+
+export function globalDir(): string {
+  return join(os.homedir(), '.explorbot');
+}
+
+export function globalEnvPath(): string {
+  return join(globalDir(), '.env');
+}
+
+export function globalConfigPath(): string {
+  return join(globalDir(), 'config.js');
+}
+
+export function findGlobalConfig(): string | null {
+  for (const name of GLOBAL_CONFIG_NAMES) {
+    const fullPath = join(globalDir(), name);
+    if (existsSync(fullPath)) return fullPath;
+  }
+  return null;
+}
+
+export function isGlobalConfigPath(configPath: string): boolean {
+  return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
+}
+
+export function sitesDir(): string {
+  return join(globalDir(), 'sites');
+}
+
+export function siteFolderName(url: string): string {
+  return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+}
+
+export function listSites(): SiteRecord[] {
+  if (!existsSync(sitesDir())) return [];
+
+  return readdirSync(sitesDir(), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => readSite(entry.name))
+    .filter((site): site is SiteRecord => !!site)
+    .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
+}
+
+export function registerSite(baseUrl: string): SiteRecord {
+  const folder = siteFolderName(baseUrl);
+  const dir = join(sitesDir(), folder);
+  for (const subDir of SITE_DIRS) {
+    mkdirSync(join(dir, subDir), { recursive: true, mode: 0o700 });
+  }
+
+  const now = new Date().toISOString();
+  const meta = {
+    url: baseUrl,
+    createdAt: readSite(folder)?.createdAt || now,
+    lastRunAt: now,
+  };
+  writeFileSync(join(dir, 'site.json'), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+
+  return { folder, dir, ...meta };
+}
+
+export function resolveSiteTarget(target?: string, defaultBaseUrl?: string): SiteTarget {
+  const raw = (target || process.env.EXPLORBOT_URL || defaultBaseUrl || '').trim();
+  if (!raw) {
+    throw new Error(withSites('No site to explore. Pass a URL to the command or set EXPLORBOT_URL.'));
+  }
+
+  if (raw.startsWith('http://') || raw.startsWith('https://')) {
+    const url = new URL(raw);
+    return { baseUrl: url.origin, path: `${url.pathname}${url.search}${url.hash}` };
+  }
+
+  if (raw.startsWith('/')) {
+    const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+    if (!base) {
+      throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
+    }
+    return { baseUrl: new URL(base).origin, path: raw };
+  }
+
+  let reference = raw;
+  let path = '/';
+  const separator = raw.indexOf('/');
+  if (separator > -1) {
+    reference = raw.slice(0, separator);
+    path = raw.slice(separator);
+  }
+
+  const site = findSite(reference);
+  if (!site) {
+    throw new Error(withSites(`Unknown site "${reference}".`));
+  }
+  return { baseUrl: site.url, path };
+}
+
+function readSite(folder: string): SiteRecord | null {
+  const dir = join(sitesDir(), folder);
+  const metaPath = join(dir, 'site.json');
+  if (!existsSync(metaPath)) return null;
+
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    new URL(meta.url);
+    return { folder, dir, url: meta.url, createdAt: meta.createdAt, lastRunAt: meta.lastRunAt };
+  } catch {
+    return null;
+  }
+}
+
+function findSite(reference: string): SiteRecord | null {
+  const normalized = reference.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+  const sites = listSites();
+  const byFolder = sites.find((site) => site.folder === normalized);
+  if (byFolder) return byFolder;
+  return sites.find((site) => new URL(site.url).host.toLowerCase() === reference.toLowerCase()) || null;
+}
+
+function withSites(message: string): string {
+  const lines = [message];
+  const sites = listSites();
+  if (sites.length) {
+    lines.push('Registered sites:');
+    for (const site of sites) lines.push(`  ${site.folder} → ${site.url}`);
+  }
+  lines.push('Explore a new site by passing its full URL, e.g. https://app.example.com/login');
+  return lines.join('\n');
+}
+
+interface SiteRecord {
+  folder: string;
+  dir: string;
+  url: string;
+  createdAt: string;
+  lastRunAt: string;
+}
+
+interface SiteTarget {
+  baseUrl: string;
+  path: string;
+}
+
+export type { SiteRecord, SiteTarget };

package/src/knowledge-tracker.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import dedent from 'dedent';
 import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
+import { ApplicationSpec } from './application-spec.ts';
 import { ConfigParser } from './config.js';
 import { getCliName } from './utils/cli-name.ts';
 import { createDebug, pluralize, tag } from './utils/logger.js';
@@ -24,8 +25,9 @@ export class KnowledgeTracker {
   private knowledgeDir: string;
   private knowledgeFiles: Knowledge[] = [];
   private isLoaded = false;
+  private applicationSpec?: ApplicationSpec;
 
-  constructor() {
+  constructor(applicationSpecPath?: string) {
     const configParser = ConfigParser.getInstance();
     const config = configParser.getConfig();
     this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
@@ -33,6 +35,12 @@ export class KnowledgeTracker {
     if (!existsSync(this.knowledgeDir)) {
       mkdirSync(this.knowledgeDir, { recursive: true });
     }
+
+    const specPath = applicationSpecPath || config.dirs?.spec;
+    if (specPath) {
+      this.applicationSpec = new ApplicationSpec(specPath);
+      tag('info').log(`Loaded application spec with ${this.applicationSpec.pageCount} documented pages`);
+    }
   }
 
   private loadKnowledgeFiles(): void {
@@ -79,6 +87,14 @@ export class KnowledgeTracker {
     `;
   }
 
+  renderRelevantContext(state: ActionResult): string {
+    return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
+  }
+
+  renderApplicationSpec(state: ActionResult): string {
+    return this.applicationSpec?.renderFor(state) || '';
+  }
+
   addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
     const configPath = configParser.getConfigPath();

package/src/utils/cli-name.ts

@@ -7,7 +7,10 @@ export function getCliName(): string {
   const ua = process.env.npm_config_user_agent || '';
   if (ua.includes('bun')) cached = 'bunx explorbot';
   else if (ua.includes('npm')) cached = 'npx explorbot';
-  else if (process.argv[1]?.endsWith('.ts')) cached = `bun ${path.relative(process.cwd(), process.argv[1])}`;
-  else cached = 'explorbot';
+  else if (process.argv[1]?.endsWith('.ts')) {
+    let script = path.relative(process.cwd(), process.argv[1]);
+    if (script.startsWith('..')) script = process.argv[1];
+    cached = `bun ${script}`;
+  } else cached = 'explorbot';
   return cached;
 }

package/src/utils/test-files.ts

@@ -67,8 +67,7 @@ export async function dryRunTestFile(filePath: string): Promise<void> {
   }
 
   const config = ConfigParser.getInstance().getConfig();
-  const configPath = ConfigParser.getInstance().getConfigPath();
-  const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+  const projectRoot = ConfigParser.getInstance().getProjectRoot();
 
   const codeceptConfig = {
     helpers: {

package/src/utils/url-matcher.ts

@@ -93,3 +93,13 @@ export function extractStatePath(url: string): string {
     return url;
   }
 }
+
+export function matchesNavigationUrl(expected: string, current: string): boolean {
+  const expectedPath = extractStatePath(expected);
+  let currentPath = extractStatePath(current);
+  if (!expectedPath.includes('#')) {
+    currentPath = currentPath.split('#')[0];
+  }
+  const normalize = (value: string) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
+  return normalize(expectedPath) === normalize(currentPath);
+}