@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/guards/worktree-undo.ts

@@ -0,0 +1,260 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { mkdir, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import uniq from 'lodash/uniq'
+
+import { refsMadeInTurn, type GitState } from './after-turn-check'
+import { git, gitOk } from './worktree-git'
+import type { SavedGit, TurnSnapshot } from './worktree-snapshot'
+
+import { FROZEN_INSTALL } from '../gates/lockfile-install'
+import { runShell } from '../shell/run-command'
+
+/**
+ * Takes a ref an agent made off, keeping its commit under `refs/luca-undone/`
+ * so nothing is lost: the refs are shared, and the engine can't tell who
+ * made one. A ref that existed before goes back to where it was.
+ */
+const undoRef = async ({
+    cwd,
+    ref,
+    before,
+}: {
+    cwd: string
+    ref: string
+    before: string | undefined
+}): Promise<void> => {
+    const now = await git({ cwd, args: ['rev-parse', '--verify', '-q', ref] })
+    if (!now.ok) return
+    const object = now.stdout.trim()
+    if (before !== undefined) {
+        await gitOk({ cwd, args: ['update-ref', ref, before, object] })
+        return
+    }
+    const kept = ref.replace(/^refs\//, 'refs/luca-undone/')
+    await gitOk({ cwd, args: ['update-ref', kept, object] })
+    await gitOk({ cwd, args: ['update-ref', '-d', ref, object] })
+}
+
+/**
+ * Drops the stash entries an agent made. The stash is shared, so each is
+ * found by its commit just before it is dropped, newest first.
+ */
+const dropStashes = async ({
+    cwd,
+    entries,
+}: {
+    cwd: string
+    entries: string[]
+}): Promise<void> => {
+    const shas = entries.map((entry) => entry.split(' ')[0] ?? '')
+    for (const sha of shas) {
+        const list = await git({ cwd, args: ['stash', 'list', '--format=%H'] })
+        const index = list.stdout.split('\n').indexOf(sha)
+        if (index !== -1) {
+            await gitOk({
+                cwd,
+                args: ['stash', 'drop', '-q', `stash@{${index}}`],
+            })
+        }
+    }
+}
+
+/**
+ * Whether HEAD is now a commit made during the turn: it moved, to a commit
+ * no ref named before the turn and that the old HEAD doesn't contain.
+ */
+export const headIsNew = async ({
+    cwd,
+    before,
+    after,
+    saved,
+}: {
+    cwd: string
+    before: GitState
+    after: GitState
+    saved: SavedGit
+}): Promise<boolean> => {
+    if (after.head === before.head || after.head === '') return false
+    if (Object.values(saved.refs).includes(after.head)) return false
+    const older = await git({
+        cwd,
+        args: ['merge-base', '--is-ancestor', after.head, before.head],
+    })
+    return !older.ok
+}
+
+/**
+ * Puts HEAD, the branch, the index, the refs the agent made, and stashes
+ * back; the files stay.
+ */
+export const restoreGit = async ({
+    cwd,
+    branch,
+    before,
+    after,
+    saved,
+    head_is_new,
+}: {
+    cwd: string
+    branch: string
+    before: GitState
+    after: GitState
+    saved: SavedGit
+    head_is_new: boolean
+}): Promise<void> => {
+    if (before.head_ref !== null) {
+        await gitOk({ cwd, args: ['symbolic-ref', 'HEAD', before.head_ref] })
+    }
+    // A mixed reset: HEAD and the branch go back, the index is emptied of
+    // the agent's staging, and the files in the worktree are left alone.
+    await gitOk({ cwd, args: ['reset', '-q', before.head] })
+    if (before.branch_ref !== null) {
+        await gitOk({
+            cwd,
+            args: ['update-ref', `refs/heads/${branch}`, before.branch_ref],
+        })
+    }
+    for (const ref of refsMadeInTurn({ before, after, head_is_new })) {
+        await undoRef({ cwd, ref, before: saved.refs[ref] })
+    }
+    await dropStashes({
+        cwd,
+        entries: after.stash.filter((entry) => !before.stash.includes(entry)),
+    })
+}
+
+/** Puts one path back how it was before the turn. */
+export const restorePath = async ({
+    cwd,
+    path,
+    before,
+}: {
+    cwd: string
+    path: string
+    before: TurnSnapshot
+}): Promise<void> => {
+    const full = join(cwd, path)
+    const bytes = before.saved[path]
+    if (bytes !== undefined && bytes !== null) {
+        await mkdir(dirname(full), { recursive: true })
+        await rm(full, { force: true, recursive: true })
+        await Bun.write(full, bytes)
+        return
+    }
+    if (bytes === undefined) {
+        const tracked = await git({
+            cwd,
+            args: ['cat-file', '-e', `${before.git.head}:${path}`],
+        })
+        if (tracked.ok) {
+            await rm(full, { force: true, recursive: true })
+            await gitOk({
+                cwd,
+                args: ['checkout', before.git.head, '--', path],
+            })
+            await gitOk({ cwd, args: ['reset', '-q', '--', path] })
+            return
+        }
+    }
+    await rm(full, { force: true, recursive: true })
+    await pruneEmptyFolders({ cwd, path })
+}
+
+/** Removes the folders a new path left empty, up to the worktree. */
+const pruneEmptyFolders = async ({
+    cwd,
+    path,
+}: {
+    cwd: string
+    path: string
+}): Promise<void> => {
+    for (let folder = dirname(path); folder !== '.'; folder = dirname(folder)) {
+        const full = join(cwd, folder)
+        if (!existsSync(full) || readdirSync(full).length > 0) return
+        await rm(full, { recursive: true, force: true })
+    }
+}
+
+/**
+ * The package folder a path under `node_modules` belongs to, such as
+ * `node_modules/@scope/name` for `node_modules/@scope/name/lib/a.js`.
+ */
+const packageFolder = (path: string): string => {
+    const parts = path.split('/')
+    const at = parts.lastIndexOf('node_modules')
+    const scoped = parts[at + 1]?.startsWith('@') === true
+    return parts.slice(0, at + (scoped ? 3 : 2)).join('/')
+}
+
+/**
+ * Puts back files an agent changed or deleted under `node_modules`. Their
+ * bytes are not kept (there are too many), so each package they belong to
+ * is removed and the engine's own install puts it back from the lockfile.
+ *
+ * @returns Why the install failed, or `null`.
+ */
+export const reinstallPackages = async ({
+    cwd,
+    paths,
+}: {
+    cwd: string
+    paths: string[]
+}): Promise<string | null> => {
+    for (const folder of uniq(paths.map(packageFolder))) {
+        await rm(join(cwd, folder), { force: true, recursive: true })
+    }
+    const result = await runShell({ command: FROZEN_INSTALL, cwd })
+    return result.exit_code === 0
+        ? null
+        : `the engine's install (${FROZEN_INSTALL}) failed, so node_modules may still hold what the agent changed:\n${result.stderr || result.stdout}`
+}
+
+/**
+ * Puts the ticket branch's own config section back, key by key: each of its
+ * keys now there is unset, then each saved entry is added back in order.
+ * Every other key in the shared `.git/config` stays as it is now, since
+ * other processes write there too. A key with no value comes back as
+ * `true`, which git reads the same.
+ *
+ * @returns Why the undo failed (such as another process holding the
+ *   config's lock), or `null`.
+ */
+export const restoreBranchConfig = async ({
+    cwd,
+    before,
+    after,
+    common_dir,
+}: {
+    cwd: string
+    before: GitState
+    after: GitState
+    common_dir: string
+}): Promise<string | null> => {
+    const file = join(common_dir, 'config')
+    const steps = [
+        ...uniq(after.branch_config.map(({ key }) => key)).map((key) => [
+            'config',
+            '--file',
+            file,
+            '--unset-all',
+            key,
+        ]),
+        ...before.branch_config.map(({ key, value }) => [
+            'config',
+            '--file',
+            file,
+            '--add',
+            key,
+            value ?? 'true',
+        ]),
+    ]
+    for (const args of steps) {
+        const result = await git({ cwd, args })
+        if (!result.ok) {
+            return `git ${args.join(' ')} failed, so the ticket branch's settings in the shared .git/config may still hold what the agent changed`
+        }
+    }
+    return null
+}

package/engine/guards/write-rules.ts

@@ -0,0 +1,149 @@
+/**
+ * Pure: which worktree paths each role may create, change, or delete.
+ */
+import { basename, isAbsolute, normalize, relative, resolve } from 'node:path'
+
+import { isWriter, type GuardArgs } from './guard-roles'
+
+import {
+    featureMapPath,
+    isFeatureMapFolder,
+    type EngineConfig,
+} from '../config/engine-config'
+import { testFilesAmong } from '../gates/test-runner'
+
+/**
+ * Worktree-relative, `..` resolved. `null` when the path leaves the worktree.
+ * macOS reaches temp folders through `/var` and `/private/var` alike, so both
+ * sides drop the `/private` prefix before they are compared.
+ */
+export const insideWorktree = ({
+    worktree,
+    path,
+}: {
+    worktree: string
+    path: string
+}): string | null => {
+    const canonical = (text: string) =>
+        text.replace(/^\/private\/(var|tmp)(?=\/|$)/, '/$1')
+    const root = canonical(resolve(worktree))
+    const full = canonical(resolve(root, path))
+    const inner = relative(root, full)
+    if (inner.startsWith('..') || isAbsolute(inner)) return null
+    return inner === '' ? '.' : inner
+}
+
+const isTestFile = ({
+    path,
+    config,
+}: {
+    path: string
+    config: EngineConfig
+}): boolean =>
+    testFilesAmong({
+        files: [path],
+        test_file_patterns: config.test_file_patterns,
+    }).length > 0
+
+/**
+ * Whether a clean worktree-relative path is part of the repo's feature map
+ * (#583): the map file itself, or, when the map is a folder (#597), any
+ * `*.md` page under it.
+ */
+const isFeatureMapPage = ({
+    path,
+    config,
+}: {
+    path: string
+    config: EngineConfig
+}): boolean => {
+    const map = featureMapPath({ config })
+    if (map === null) return false
+    return isFeatureMapFolder({ path: map })
+        ? path.startsWith(`${map}/`) && path.endsWith('.md')
+        : path === map
+}
+
+/**
+ * Whether a clean worktree-relative path matches the repo's
+ * `test_helper_patterns` (#619): a non-test file the test-writer may write.
+ */
+export const isTestHelper = ({
+    path,
+    config,
+}: {
+    path: string
+    config: EngineConfig
+}): boolean =>
+    (config.test_helper_patterns ?? []).some((pattern) =>
+        new Bun.Glob(pattern).match(path)
+    )
+
+/** The lockfiles a package install writes. The engine owns them. */
+export const LOCKFILES = [
+    'bun.lock',
+    'bun.lockb',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+]
+
+/**
+ * Whether a worktree-relative path is the package install's: a lockfile, or
+ * anything under a `node_modules` folder. Only the engine's install gate
+ * writes these; no agent does.
+ *
+ * @example
+ * isInstallPath('bun.lock') // true
+ * isInstallPath('packages/app/node_modules/zod/index.js') // true
+ * isInstallPath('src/sum.ts') // false
+ */
+export const isInstallPath = (path: string): boolean =>
+    LOCKFILES.includes(basename(path)) ||
+    normalize(path).split('/').includes('node_modules')
+
+/**
+ * Whether an agent may create, change, or delete a worktree-relative path.
+ * Test-writers write test files only, the feature map when the repo has
+ * one (#583), or any page of a folder map (#597), and files matching
+ * `test_helper_patterns` (#619); implementers write anything but test
+ * files (unless they may edit tests) and test setup files; reviewers and the
+ * learner write nothing. No role writes a test setup file, `.git`, what
+ * the package install writes (lockfiles, `node_modules`), or outside its
+ * worktree.
+ *
+ * @example
+ * mayWrite({ role: 'test-writer', may_edit_tests: true, path: 'src/sum.test.ts', config }) // true
+ * mayWrite({ role: 'implementer', may_edit_tests: false, path: 'src/sum.test.ts', config }) // false
+ * mayWrite({ role: 'implementer', may_edit_tests: true, path: 'src/sum.test.ts', config }) // true: a refactor ticket
+ */
+export const mayWrite = ({
+    role,
+    may_edit_tests,
+    path,
+    config,
+}: GuardArgs & {
+    path: string
+    config: EngineConfig
+}): boolean => {
+    if (!isWriter(role) || isAbsolute(path)) return false
+    const clean = normalize(path).replace(/^\.\//, '')
+    if (clean === '.' || clean.startsWith('..')) return false
+    if (clean === '.git' || clean.startsWith('.git/')) return false
+    if (config.test_setup_files.includes(clean)) return false
+    if (isInstallPath(clean)) return false
+    const test = isTestFile({ path: clean, config })
+    // The test-writer may also write the repo's feature map, when it has one
+    // (#583): the file, or any page of a folder map (#597); and its test
+    // helpers (#619).
+    if (role === 'test-writer') {
+        return (
+            may_edit_tests &&
+            (test ||
+                isFeatureMapPage({ path: clean, config }) ||
+                isTestHelper({ path: clean, config }))
+        )
+    }
+    return !test || may_edit_tests
+}

package/engine/index.ts

@@ -20,8 +20,10 @@ export {
     agentOptions,
     BANNED_ENV,
     CLAUDE_MODEL,
+    checkLaunchModel,
     checkModel,
     MAX_TURNS,
+    MODEL_NAMES,
     resultJsonSchema,
 } from './agents/claude-options'
 export {
@@ -60,9 +62,13 @@ export {
 } from './board/paseo-board-link'
 export {
     bunTestCommands,
+    DecisionModelConfigSchema,
+    decisionModelOf,
     ENGINE_CONFIG_FILE,
     EngineConfigSchema,
+    hasSlowTests,
     loadEngineConfig,
+    slowTestCommands,
     testCommands,
     TestResultsSchema,
     type EngineConfig,
@@ -128,6 +134,7 @@ export {
     shipFinalReview,
 } from './core/execute-final-review'
 export { finalFixerPrompt, lensPrompt } from './core/final-review-text'
+export { evidenceSection } from './core/evidence-text'
 export { pullRequestText } from './core/pull-request-text'
 export {
     DEFAULT_MAX_STEPS,
@@ -192,27 +199,41 @@ export {
 } from './intake/intake-checks'
 export * from './intake/intake-schemas'
 export {
-    createTypeSafeJev,
-    JEV_MODEL,
-    JEV_URL,
-    type JevClient,
-    type JevFetch,
-    type JevReply,
-} from './jev/jev-client'
+    clefUrl,
+    createClefClient,
+    type ClefCredentials,
+    type DecisionModelClient,
+    type DecisionModelFetch,
+    type DecisionModelReply,
+} from './jev/clef-client'
+export {
+    CLOUDFLARE_ACCOUNT_ID,
+    CLOUDFLARE_API_TOKEN,
+    CLOUDFLARE_AUTH_TOKEN,
+    DECISION_MODEL_KEYS,
+    describeDecisionModelCredentials,
+    loadDecisionModelCredentials,
+    lucaEnvFile,
+    missingKeyLines,
+    noCredentialsText,
+    parseEnvFile,
+    type DecisionModelCredentials,
+    type DecisionModelKey,
+} from './jev/decision-model-credentials'
 export {
     JEV_CANDIDATE_SKILLS,
     JEV_FAILURE_TEXT_CHARS,
     JEV_FIXED_MODEL,
-    JEV_MODEL_OPTIONS,
     jevAsksAfter,
     jevAsksBefore,
     type JevAsk,
 } from './jev/jev-jobs'
 export * from './jev/jev-schemas'
 export {
-    askJevInShadow,
     DEFAULT_JEV_TIMEOUT_MS,
+    shadowAsker,
     type JevShadow,
+    type ShadowAsker,
 } from './jev/jev-shadow'
 export {
     createJournal,

package/engine/intake/criteria-checks.ts

@@ -0,0 +1,114 @@
+import uniq from 'lodash/uniq'
+
+/** The fix intake asks for when a criterion leaves text to guess. */
+export const PIN_TEXT = 'pin the exact text'
+
+/** The fix intake asks for when no agent can test a criterion. */
+export const UNTESTABLE_TEXT =
+    'no agent can check this; move it out of the acceptance criteria'
+
+/** The fix intake asks for when a criterion describes what stays as it is. */
+export const UNCHANGED_TEXT =
+    "describes behaviour that doesn't change, so no test can fail first; move it out of the acceptance criteria (for example into the ticket's notes)"
+
+/**
+ * Text that leaves an agent to guess, caught anywhere in a criterion, inside
+ * quotes and code spans too (#541).
+ */
+const PLACEHOLDERS: RegExp[] = [
+    /<[^<>\n]+>/g,
+    /\be\.g\./gi,
+    /\betc\./gi,
+    /\bTBD\b/g,
+    /\bTODO\b/g,
+    /\.\.\.|…/g,
+    /(?<![\w'-])[NMXY](?![\w'-])/g,
+]
+
+/** Asks no agent can test, caught outside code spans only (#541). */
+const UNTESTABLE_ASKS: RegExp[] = [
+    /\bscreenshots?\b/gi,
+    /\bchangesets?\b/gi,
+    /\bADR[\s#-]*\d+/g,
+]
+
+/**
+ * Phrases for behaviour that doesn't change, caught outside code spans only
+ * (#653): no test can fail first on them.
+ */
+const UNCHANGED_PHRASES: RegExp[] = [
+    /\bunchanged\b/gi,
+    /\bstays? the same\b/gi,
+    /\bas (?:today|before)\b/gi,
+]
+
+/** Inline code spans: a run of backticks up to the same run. */
+const CODE_SPAN = /(`+)[\s\S]*?\1/g
+
+/** Every match of `patterns` in `text`, in pattern order, once each. */
+const found = ({
+    text,
+    patterns,
+}: {
+    text: string
+    patterns: RegExp[]
+}): string[] =>
+    uniq(
+        patterns.flatMap((pattern) =>
+            [...text.matchAll(pattern)].map(([match]) => match)
+        )
+    )
+
+/** `text` as a markdown code span, fenced past any backticks inside it. */
+const asCode = (text: string): string => {
+    const longest = Math.max(
+        0,
+        ...[...text.matchAll(/`+/g)].map(([run]) => run.length)
+    )
+    const fence = '`'.repeat(longest + 1)
+    return longest === 0
+        ? `${fence}${text}${fence}`
+        : `${fence} ${text} ${fence}`
+}
+
+/**
+ * Intake's problems with one ticket's acceptance criteria: a placeholder
+ * anywhere in a criterion, an untestable ask (a screenshot, a changeset,
+ * an ADR number) outside its code spans, or, outside its code spans, words
+ * for behaviour that doesn't change ("unchanged", "stays the same", "as
+ * today", "as before"), once per criterion. Each problem names the ticket,
+ * quotes the criterion, and says what to do. Pure. Empty when all are clean.
+ *
+ * @example
+ * criteriaProblems({ ticket: 12, criteria: [{ id: 'AC1', text: 'Retries N times' }] })
+ * // ['Acceptance criterion AC1 of #12 leaves text to guess (`N`): pin the exact text. It reads: `Retries N times`']
+ */
+export const criteriaProblems = ({
+    ticket,
+    criteria,
+}: {
+    ticket: number
+    criteria: { id: string; text: string }[]
+}): string[] =>
+    criteria.flatMap(({ id, text }) => {
+        const named = `Acceptance criterion ${id} of #${ticket}`
+        const quoted = `It reads: ${asCode(text)}`
+        const placeholders = found({ text, patterns: PLACEHOLDERS })
+        const prose = text.replace(CODE_SPAN, ' ')
+        const asks = found({ text: prose, patterns: UNTESTABLE_ASKS })
+        const unchanged =
+            found({ text: prose, patterns: UNCHANGED_PHRASES }).length > 0
+        return [
+            ...(placeholders.length === 0
+                ? []
+                : [
+                      `${named} leaves text to guess (${placeholders.map(asCode).join(', ')}): ${PIN_TEXT}. ${quoted}`,
+                  ]),
+            ...(asks.length === 0
+                ? []
+                : [
+                      `${named} asks for ${asks.map(asCode).join(', ')}: ${UNTESTABLE_TEXT}. ${quoted}`,
+                  ]),
+            ...(unchanged ? [`${named} ${UNCHANGED_TEXT}. ${quoted}`] : []),
+        ]
+    })