kaloko 0.4.9 → 0.4.11

package/src/lib/init-detect.mjs

@@ -0,0 +1,219 @@
+// Smarter `kaloko init` (#26): what the project is (framework, dev server command and URL, locales from the i18n
+// config, main routes) and a first scenario that walks on the first try. Reads files only; never runs the project.
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { routeOf } from './affected-core.mjs'
+
+const read = (root, f) => readFile(join(root, f), 'utf8').catch(() => null)
+const exists = (root, f) => stat(join(root, f)).then(() => true, () => false)
+const firstOf = async (root, files) => { for (const f of files) { const t = await read(root, f); if (t != null) return { file: f, text: t } } return null }
+
+const FRAMEWORKS = [
+  ['next', 'Next.js', ['next'], 3000],
+  ['nuxt', 'Nuxt', ['nuxt', 'nuxt3'], 3000],
+  ['sveltekit', 'SvelteKit', ['@sveltejs/kit'], 5173],
+  ['remix', 'Remix / React Router', ['@remix-run/dev', '@remix-run/react', '@react-router/dev'], 5173],
+  ['astro', 'Astro', ['astro'], 4321],
+  ['gatsby', 'Gatsby', ['gatsby'], 8000],
+  ['angular', 'Angular', ['@angular/core'], 4200],
+  ['cra', 'Create React App', ['react-scripts'], 3000],
+  ['vite', 'Vite', ['vite'], 5173]
+]
+
+/** Framework, package manager and dev server (command, port, URL). */
+async function detectStack (root) {
+  const pkgText = await read(root, 'package.json')
+  let pkg = null
+  try { pkg = pkgText ? JSON.parse(pkgText) : null } catch {}
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) }
+  const pm = (await exists(root, 'pnpm-lock.yaml')) ? 'pnpm' : (await exists(root, 'yarn.lock')) ? 'yarn' : (await exists(root, 'bun.lockb')) || (await exists(root, 'bun.lock')) ? 'bun' : 'npm'
+  const runCmd = (script) => (pm === 'npm' ? `npm run ${script}` : pm === 'bun' ? `bun run ${script}` : `${pm} ${script}`)
+  let framework = null
+  for (const [id, name, names, port] of FRAMEWORKS) if (names.some((n) => deps[n])) { framework = { id, name, port }; break }
+  const gem = await read(root, 'Gemfile')
+  if (!framework && gem && /^\s*gem\s+['"]rails['"]/m.test(gem)) framework = { id: 'rails', name: 'Rails', port: 3000 }
+  if (!framework && await exists(root, 'manage.py')) framework = { id: 'django', name: 'Django', port: 8000 }
+  if (!framework && await exists(root, 'artisan')) framework = { id: 'laravel', name: 'Laravel', port: 8000 }
+  let command = null; let port = framework?.port || 3000
+  if (pkg?.scripts) {
+    const script = ['dev', 'start', 'serve', 'develop'].find((s) => pkg.scripts[s])
+    if (script) {
+      command = runCmd(script)
+      const m = pkg.scripts[script].match(/(?:--port[ =]|-p\s+|PORT=)(\d{2,5})/)
+      if (m) port = Number(m[1])
+    }
+  }
+  if (framework?.id === 'rails') command = (await exists(root, 'bin/dev')) ? 'bin/dev' : 'bin/rails server'
+  if (framework?.id === 'django') command = 'python manage.py runserver'
+  if (framework?.id === 'laravel') command = 'php artisan serve'
+  // a port in the bundler config wins over the default
+  const vite = await firstOf(root, ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'])
+  const vp = vite?.text.match(/server\s*:\s*{[^}]*port\s*:\s*(\d{2,5})/)
+  if (vp && !/(?:--port|-p\s|PORT=)/.test(pkg?.scripts?.dev || '')) port = Number(vp[1])
+  const nuxtCfg = framework?.id === 'nuxt' ? await firstOf(root, ['nuxt.config.ts', 'nuxt.config.js']) : null
+  const np = nuxtCfg?.text.match(/devServer\s*:\s*{[^}]*port\s*:\s*(\d{2,5})/)
+  if (np) port = Number(np[1])
+  return { framework, pm, command, port, url: `http://localhost:${port}`, name: pkg?.name || null }
+}
+
+const LOCALE = /^[a-z]{2}(?:-[A-Za-z]{2,4})?$/
+const listOf = (src) => [...String(src || '').matchAll(/['"`]([a-z]{2}(?:-[A-Za-z]{2,4})?)['"`]/g)].map((m) => m[1])
+const codesOf = (src) => { const codes = [...String(src || '').matchAll(/code\s*:\s*['"`]([a-z]{2}(?:-[A-Za-z]{2,4})?)['"`]/g)].map((m) => m[1]); return codes.length ? codes : listOf(src) }
+const ordered = (list, def) => { const u = [...new Set(list)]; return def && u.includes(def) ? [def, ...u.filter((l) => l !== def)] : u }
+
+/** Locales from the i18n config: { list, default, source, prefix: 'always'|'except-default'|'none' } or null. */
+async function detectLocales (root, framework) {
+  // Next.js pages router i18n
+  const next = await firstOf(root, ['next.config.js', 'next.config.mjs', 'next.config.ts'])
+  const ni = next?.text.match(/i18n\s*:\s*{([\s\S]*?)}/)
+  if (ni) {
+    const list = listOf((ni[1].match(/locales\s*:\s*\[([^\]]*)\]/) || [])[1])
+    const def = (ni[1].match(/defaultLocale\s*:\s*['"`]([^'"`]+)/) || [])[1]
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: next.file, prefix: 'except-default' }
+  }
+  // next-intl, i18next routing files
+  const routing = await firstOf(root, ['src/i18n/routing.ts', 'src/i18n/routing.js', 'i18n/routing.ts', 'i18n/routing.js', 'src/i18n.ts', 'i18n.ts', 'src/i18n/config.ts', 'i18n/config.ts', 'src/middleware.ts', 'middleware.ts'])
+  const rl = routing?.text.match(/locales\s*:\s*\[([^\]]*)\]/) || routing?.text.match(/(?:export\s+)?const\s+locales\s*=\s*\[([^\]]*)\]/)
+  if (rl && listOf(rl[1]).length) {
+    const def = (routing.text.match(/defaultLocale\s*[:=]\s*['"`]([^'"`]+)/) || [])[1]
+    const prefix = /localePrefix\s*:\s*['"`](as-needed)['"`]/.test(routing.text) ? 'except-default' : /localePrefix\s*:\s*['"`]never['"`]/.test(routing.text) ? 'none' : 'always'
+    const list = listOf(rl[1])
+    return { list: ordered(list, def), default: def || list[0], source: routing.file, prefix }
+  }
+  // Nuxt i18n
+  const nuxt = framework?.id === 'nuxt' ? await firstOf(root, ['nuxt.config.ts', 'nuxt.config.js']) : null
+  const nx = nuxt?.text.match(/i18n\s*:\s*{([\s\S]*?)\n\s{0,4}}/)
+  if (nx) {
+    const block = nx[1]
+    const list = codesOf((block.match(/locales\s*:\s*\[([\s\S]*?)\]/) || [])[1])
+    const def = (block.match(/defaultLocale\s*:\s*['"`]([^'"`]+)/) || [])[1]
+    const strategy = (block.match(/strategy\s*:\s*['"`]([^'"`]+)/) || [])[1] || 'prefix_except_default'
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: nuxt.file, prefix: strategy === 'prefix' ? 'always' : strategy === 'no_prefix' ? 'none' : 'except-default' }
+  }
+  // Paraglide / inlang (SvelteKit and others)
+  const inlang = await read(root, 'project.inlang/settings.json')
+  if (inlang) {
+    try {
+      const s = JSON.parse(inlang); const list = s.locales || s.languageTags || []; const def = s.baseLocale || s.sourceLanguageTag
+      if (list.length) return { list: ordered(list, def), default: def || list[0], source: 'project.inlang/settings.json', prefix: 'except-default' }
+    } catch {}
+  }
+  // Rails
+  if (framework?.id === 'rails') {
+    const app = await read(root, 'config/application.rb') || ''
+    const avail = (app.match(/available_locales\s*=\s*\[([^\]]*)\]/) || [])[1]
+    const def = (app.match(/default_locale\s*=\s*:?['"]?([a-z]{2}(?:-[A-Z]{2})?)/) || [])[1]
+    let list = avail ? [...avail.matchAll(/:?['"]?([a-z]{2}(?:-[A-Z]{2})?)['"]?/g)].map((m) => m[1]) : []
+    if (!list.length) list = (await readdir(join(root, 'config/locales')).catch(() => [])).map((f) => f.replace(/\.(ya?ml|rb)$/, '')).filter((f) => LOCALE.test(f))
+    const routes = await read(root, 'config/routes.rb') || ''
+    if (list.length) return { list: ordered(list, def), default: def || list[0], source: avail ? 'config/application.rb' : 'config/locales', prefix: /scope\s+['"]\(?:locale\)?['"]|scope\s+['"]\/?:locale['"]/.test(routes) ? (/\(:locale\)/.test(routes) ? 'except-default' : 'always') : 'none' }
+  }
+  // message folders: messages/en.json, locales/cs.json, public/locales/en/…, src/locales/de.ts
+  for (const dir of ['messages', 'locales', 'lang', 'src/locales', 'src/messages', 'src/lang', 'public/locales', 'i18n', 'src/i18n']) {
+    const names = (await readdir(join(root, dir)).catch(() => [])).map((f) => f.replace(/\.(json|ya?ml|ts|js)$/, '')).filter((f) => LOCALE.test(f))
+    if (names.length) {
+      const appDir = await firstOf(root, ['app/[locale]/page.tsx', 'src/app/[locale]/page.tsx', 'app/[locale]/layout.tsx', 'src/app/[locale]/layout.tsx', 'app/[lang]/page.tsx', 'src/app/[lang]/page.tsx'])
+      return { list: ordered(names, names.includes('en') ? 'en' : null), default: names.includes('en') ? 'en' : names[0], source: dir, prefix: appDir ? 'always' : 'none' }
+    }
+  }
+  return null
+}
+
+const SOURCE_DIRS = ['app', 'src/app', 'pages', 'src/pages', 'src/routes', 'app/routes', 'app/pages']
+
+async function filesUnder (root, dir, out = [], depth = 0) {
+  if (depth > 8 || out.length > 5000) return out
+  let entries = []
+  try { entries = await readdir(join(root, dir), { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    const p = `${dir}/${e.name}`
+    if (e.isDirectory()) { if (!['node_modules', 'api', 'components', 'lib'].includes(e.name) && !e.name.startsWith('.')) await filesUnder(root, p, out, depth + 1) } else out.push(p)
+  }
+  return out
+}
+
+/** Static routes from route files (any locale segment removed) or Rails routes; '/' first, shallow before deep. */
+async function detectRoutes (root, framework) {
+  const found = new Map()
+  if (framework?.id === 'rails') {
+    const text = await read(root, 'config/routes.rb') || ''
+    if (/^\s*root\b/m.test(text)) found.set('/', 'config/routes.rb')
+    for (const m of text.matchAll(/^\s*(?:get|resources|resource)\s+[:'"]\/?([a-z][\w/-]*)['"]?/gm)) found.set('/' + m[1].replace(/_/g, '-'), 'config/routes.rb')
+  } else {
+    for (const dir of SOURCE_DIRS) {
+      for (const f of await filesUnder(root, dir)) {
+        if (!/\.(m?[jt]sx?|vue|svelte|astro|mdx?)$/.test(f) || /\/(_|\[\.\.\.)/.test(f) && !/\/\[(locale|lang)\]\//.test(f)) continue
+        const r = routeOf(f)
+        if (!r || r.scope !== 'page' || /\/api(\/|$)/.test(r.route)) continue
+        const route = r.route.replace(/^\/:(locale|lang|lng)(?=\/|$)/, '') || '/'
+        if (/[:*]/.test(route)) continue
+        if (!found.has(route)) found.set(route, f)
+      }
+    }
+  }
+  const skip = /^\/(api|admin|_|auth|oauth|callback|404|500|error)(\/|$)/
+  return [...found].filter(([p]) => !skip.test(p)).map(([path, file]) => ({ path, file })).sort((a, b) => (a.path === '/' ? -1 : b.path === '/' ? 1 : a.path.split('/').length - b.path.split('/').length || a.path.localeCompare(b.path)))
+}
+
+/** Everything init can tell about the project. */
+export async function detectProject (root) {
+  const stack = await detectStack(root)
+  const locales = await detectLocales(root, stack.framework)
+  const routes = await detectRoutes(root, stack.framework)
+  return { ...stack, locales, routes }
+}
+
+const words = (p) => p === '/' ? 'Home' : p.split('/').filter(Boolean).pop().replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase())
+const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+
+/** A path per locale for the locale strategy: prefix always, except the default locale, or none. */
+export function localizedPath (path, locales) {
+  if (!locales || locales.prefix === 'none' || locales.list.length < 2) return path
+  return Object.fromEntries(locales.list.map((l) => [l, locales.prefix === 'except-default' && l === locales.default ? path : `/${l}${path === '/' ? '' : path}`]))
+}
+
+/** The first scenario: the main routes, one screen each, that a walk can open as they are. */
+export function initScenario (d, { max = 6, project = null } = {}) {
+  const routes = (d.routes.length ? d.routes : [{ path: '/', file: null }]).slice(0, max)
+  const name = project || d.name || 'app'
+  const ids = new Set()
+  const nodes = routes.map((r, i) => {
+    let id = r.path === '/' ? 'home' : slug(r.path) || `page-${i + 1}`
+    while (ids.has(id)) id += `-${i + 1}`
+    ids.add(id)
+    const title = words(r.path)
+    return {
+      id, kind: 'screen', title, path: localizedPath(r.path, d.locales),
+      purpose: `A visitor sees the ${title.toLowerCase()} page and can tell what to do next.`,
+      execution: i === 0
+        ? { strategy: 'playwright', script: 'steps/consent.mjs', instructions: `Open ${r.path} as a new visitor and accept the consent dialog if there is one.` }
+        : { strategy: 'playwright', script: 'steps/open.mjs', instructions: `Open ${r.path}.` },
+      criteria: [
+        { id: 'AC1', text: 'No errors in the browser console', check: { type: 'deterministic', assert: 'no_console_errors' } },
+        { id: 'AC2', text: 'The page makes its purpose clear', check: { type: 'semantic', question: `Does the first screen make clear what the ${title.toLowerCase()} page offers and what the visitor can do next?`, scope: 'main, body' } }
+      ]
+    }
+  })
+  return {
+    schema: 'qawalk.scenario.v1',
+    id: `${slug(name).toUpperCase() || 'APP'}-MAIN`,
+    title: `Main pages of ${name}`,
+    kind: 'flow', version: 1,
+    locales: d.locales?.list?.slice(0, 6) || ['en'],
+    viewports: { desktop: [1280, 800], mobile: [390, 844] },
+    environments: ['local'],
+    lanes: ['Visitor'],
+    nodes,
+    edges: nodes.slice(1).map((n) => ({ from: nodes[0].id, to: n.id, label: 'visit', kind: 'alt' }))
+  }
+}
+
+/** One paragraph for the terminal. */
+export function formatDetection (d, root) {
+  const lines = [`Detected ${d.framework ? d.framework.name : 'no known framework'}${d.command ? `; dev server: ${d.command}` : ''} → ${d.url}`]
+  if (d.locales) lines.push(`  locales: ${d.locales.list.join(', ')} (from ${d.locales.source}; ${d.locales.prefix === 'none' ? 'no locale in the URL' : d.locales.prefix === 'always' ? 'every locale prefixes the URL' : `/${d.locales.list.find((l) => l !== d.locales.default) || 'xx'}/… except ${d.locales.default}`})`)
+  else lines.push('  locales: none found in an i18n config (the scenario uses en)')
+  lines.push(d.routes.length ? `  routes: ${d.routes.slice(0, 8).map((r) => r.path).join(', ')}${d.routes.length > 8 ? `, +${d.routes.length - 8} more` : ''}` : '  routes: none found in route files (the scenario starts at /)')
+  return lines.join('\n')
+}
+

package/src/lib/onboarding.mjs

@@ -10,16 +10,23 @@ export const realOrg = (org) => (typeof org === 'string' && /^[a-z0-9][a-z0-9-]{
 /** Address of the organization's sample run on the service. */
 export const sampleUrl = (base, org) => `${String(base).replace(/\/$/, '')}/${org}/sample`
 
-/** Lines printed at the end of `kaloko init`. */
-export function initNextSteps ({ base, org, loggedIn = false }) {
+/**
+ * Lines printed at the end of `kaloko init`. `devServer` ({ command, url }) when init found the app's dev server but it
+ * is not answering yet; `scenario` the path of the first scenario init drafted, which then is the first real flow.
+ */
+export function initNextSteps ({ base, org, loggedIn = false, devServer = null, scenario = null }) {
   const o = realOrg(org)
-  return [
-    'Next:',
-    loggedIn ? '  1. Signed in already (KALOKO_TOKEN found).' : '  1. npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)',
-    o ? `  2. Try a review on the sample run: ${sampleUrl(base, o)}` : '  2. Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.',
-    '  3. Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:',
-    `     "${FIRST_FLOW_PROMPT}"`
+  const steps = [
+    loggedIn ? 'Signed in already (KALOKO_TOKEN found).' : 'npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)'
   ]
+  if (devServer) steps.push(`${devServer.command || 'start your app'}   (the dev server is not answering on ${devServer.url} yet)`)
+  steps.push(o ? `Try a review on the sample run: ${sampleUrl(base, o)}` : 'Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.')
+  if (scenario) steps.push(`Your first real flow: npx kaloko start --scenario ${scenario} --env local && npx kaloko walk`)
+  else steps.push('Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:', `   "${FIRST_FLOW_PROMPT}"`)
+  const lines = ['Next:']
+  let n = 0
+  for (const s of steps) lines.push(s.startsWith('   "') ? `  ${s}` : `  ${++n}. ${s}`)
+  return lines
 }
 
 /** Lines printed after a successful `kaloko login`. */

package/src/lib/pr.mjs

@@ -52,8 +52,11 @@ export function prCommentBody ({ manifest, url, at = new Date() }) {
  * Creates or updates the scenario's comment on the current branch's PR.
  * @returns {{ ok: boolean, action?: 'created'|'updated', url?: string, reason?: string }}
  */
-export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun }) {
-  const view = await run('gh', ['pr', 'view', '--json', 'number,url,headRepository,headRepositoryOwner'], cwd)
+export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun, vars = process.env, fetchImpl = fetch }) {
+  // GitLab merge request pipelines: a note on the merge request through the API
+  if (vars.GITLAB_CI && vars.CI_MERGE_REQUEST_IID) return upsertMrNote({ manifest, url, vars, fetchImpl })
+  // in CI the checkout is often a detached commit: KALOKO_PR (kaloko ci preview-url sets it) names the pull request
+  const view = await run('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,headRepository,headRepositoryOwner'], cwd)
   if (view == null) return { ok: false, reason: 'gh is not installed, not signed in, or this branch has no pull request' }
   let pr
   try { pr = JSON.parse(view) } catch { return { ok: false, reason: 'gh pr view returned no JSON' } }
@@ -73,6 +76,25 @@ export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun })
   return r == null ? { ok: false, reason: 'could not create the comment' } : { ok: true, action: 'created', url: r.trim() || pr.url }
 }
 
+/** One note per scenario on a GitLab merge request (KALOKO_GITLAB_TOKEN: a project access token with the api scope). */
+export async function upsertMrNote ({ manifest, url, vars = process.env, fetchImpl = fetch }) {
+  const token = vars.KALOKO_GITLAB_TOKEN || vars.GITLAB_TOKEN
+  if (!token) return { ok: false, reason: 'set KALOKO_GITLAB_TOKEN (a project access token with the api scope) to comment on the merge request' }
+  const notes = `${vars.CI_API_V4_URL}/projects/${encodeURIComponent(vars.CI_PROJECT_ID)}/merge_requests/${vars.CI_MERGE_REQUEST_IID}/notes`
+  const headers = { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' }
+  const body = prCommentBody({ manifest, url })
+  const link = (id) => `${vars.CI_MERGE_REQUEST_PROJECT_URL || vars.CI_PROJECT_URL}/-/merge_requests/${vars.CI_MERGE_REQUEST_IID}#note_${id}`
+  try {
+    const list = await fetchImpl(`${notes}?per_page=100&sort=desc`, { headers })
+    if (!list.ok) return { ok: false, reason: `GitLab answered ${list.status} listing notes` }
+    const mine = (await list.json()).find((n) => String(n.body || '').includes(marker(manifest.scenario.id)))
+    const res = await fetchImpl(mine ? `${notes}/${mine.id}` : notes, { method: mine ? 'PUT' : 'POST', headers, body: JSON.stringify({ body }) })
+    if (!res.ok) return { ok: false, reason: `GitLab answered ${res.status}` }
+    const note = await res.json()
+    return { ok: true, action: mine ? 'updated' : 'created', url: link(note.id || mine?.id) }
+  } catch (e) { return { ok: false, reason: e.message } }
+}
+
 async function defaultRun (cmd, args, cwd) {
   try { const { stdout } = await exec(cmd, args, { cwd, timeout: 30000, maxBuffer: 4 * 1024 * 1024 }); return stdout } catch { return null }
 }