@alecsibilia/luca 14.0.0-alpha.23 → 14.0.0-alpha.25

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.25
+
+No changes in this release.
+
+## 14.0.0-alpha.24
+
+No changes in this release.
+
 ## 14.0.0-alpha.23
 
 No changes in this release.

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.23",
+    "version": "14.0.0-alpha.25",
     "private": true,
     "type": "module"
 }

package/board/server/luca-version.ts

@@ -1,2 +1,2 @@
 /** The Luca version of this board, stamped when the package was packed. */
-export const LUCA_VERSION: string = "14.0.0-alpha.23"
+export const LUCA_VERSION: string = "14.0.0-alpha.25"

package/engine/agents/claude-options.ts

@@ -173,7 +173,7 @@ export const resultJsonSchema = ({
  * hooks.
  *
  * @example
- * const options = agentOptions({ role, may_edit_tests, cwd, model: CLAUDE_MODEL, effort: 'xhigh', claude_path, config, common_git_dir, home, env, guard_hook, luca_server: null, delivery_hook: null })
+ * const options = agentOptions({ role, may_edit_tests, cwd, model: CLAUDE_MODEL, effort: 'xhigh', claude_path, config, common_git_dir, home, user_temp_dir, env, guard_hook, luca_server: null, delivery_hook: null })
  */
 export const agentOptions = ({
     role,
@@ -185,6 +185,7 @@ export const agentOptions = ({
     config,
     common_git_dir,
     home,
+    user_temp_dir,
     env,
     guard_hook,
     luca_server,
@@ -203,6 +204,8 @@ export const agentOptions = ({
     config: EngineConfig
     common_git_dir: string
     home: string
+    /** macOS's per-user temp folder (`darwinUserTempDir`), or `null`. */
+    user_temp_dir: string | null
     env: Record<string, string>
     guard_hook: HookCallback
     /** The engine's `luca` server (`createLucaServer`), or `null` for none. */
@@ -253,6 +256,7 @@ export const agentOptions = ({
             worktree: cwd,
             common_git_dir,
             home,
+            user_temp_dir,
             config,
         }),
         env,

package/engine/agents/common-instructions.ts

@@ -5,7 +5,7 @@
  */
 import type { AgentRole } from './role-results'
 
-import type { EngineConfig } from '../config/engine-config'
+import { givesPerTestResults, type EngineConfig } from '../config/engine-config'
 import {
     HELPER_MODEL,
     HELPER_TOOLS,
@@ -30,9 +30,11 @@ export const shellRules = ({
     const guard = guardRoleOf({ role })
     const { tests, others } = checkCommands({ role: guard, config })
     const commands = [
+        // The guard lets args follow a test command just when it gives
+        // per-test results; only `bun test` takes test files among them.
         ...tests.map(({ run, results }) =>
-            results === 'bun'
-                ? `\`${run}\` (you may add test files or options after it)`
+            givesPerTestResults(results)
+                ? `\`${run}\` (you may add ${results === 'bun' ? 'test files or options' : 'options'} after it)`
                 : `\`${run}\``
         ),
         ...others.map((command) => `\`${command}\``),

package/engine/agents/launch-paths.ts

@@ -1,8 +1,10 @@
 /**
  * Where the Claude launcher finds things on disk: the real path of the
- * `claude` binary, and the repo's common git dir (shared by its worktrees).
+ * `claude` binary, the repo's common git dir (shared by its worktrees), and
+ * macOS's per-user temp folder.
  */
 import { realpathSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
 
 import { runCommand } from '../shell/run-command'
 
@@ -27,3 +29,41 @@ export const commonGitDir = async ({
     }
     return realpathSync(result.stdout.trim())
 }
+
+/** The command that prints macOS's per-user temp folder. */
+export const GETCONF_USER_TEMP_DIR = ['getconf', 'DARWIN_USER_TEMP_DIR']
+
+/**
+ * The real path of macOS's per-user temp folder (`getconf
+ * DARWIN_USER_TEMP_DIR`, such as `/private/var/folders/ab/cd1234/T`), or
+ * `null` off macOS, or when `getconf` fails or names no folder there.
+ *
+ * A sandboxed writer needs it: Foundation stages every atomic write there,
+ * not in `$TMPDIR`, so `swift test` and `xcodebuild` can't rebuild without
+ * it ("unable to write manifest ... Operation not permitted").
+ *
+ * @example
+ * const user_temp_dir = await darwinUserTempDir({ platform: process.platform, getconf: GETCONF_USER_TEMP_DIR })
+ */
+export const darwinUserTempDir = async ({
+    platform,
+    getconf,
+}: {
+    platform: NodeJS.Platform
+    /** The command to ask; the launcher passes `GETCONF_USER_TEMP_DIR`. */
+    getconf: string[]
+}): Promise<string | null> => {
+    if (platform !== 'darwin') return null
+    try {
+        const result = await runCommand({
+            cmd: getconf,
+            cwd: '/',
+            timeout_ms: 10_000,
+        })
+        const path = result.stdout.trim()
+        if (result.exit_code !== 0 || !isAbsolute(path)) return null
+        return realpathSync(path)
+    } catch {
+        return null
+    }
+}

package/engine/agents/launch-session.ts

@@ -25,7 +25,12 @@ import {
 } from './claude-messages'
 import { agentEnv, agentOptions, checkLaunchModel } from './claude-options'
 import { createInputChannel } from './input-channel'
-import { commonGitDir, realClaudePath } from './launch-paths'
+import {
+    commonGitDir,
+    darwinUserTempDir,
+    GETCONF_USER_TEMP_DIR,
+    realClaudePath,
+} from './launch-paths'
 import { createDeliveryHook, createLucaServer } from './message-tool'
 import {
     nextOutcome,
@@ -116,6 +121,10 @@ export const createLaunch = ({
             config,
             common_git_dir: gitDir,
             home: realpathSync(homedir()),
+            user_temp_dir: await darwinUserTempDir({
+                platform: process.platform,
+                getconf: GETCONF_USER_TEMP_DIR,
+            }),
             env: agentEnv({ source: process.env }),
             guard_hook: createGuardHook({
                 role: guardRoleOf({ role }),

package/engine/agents/writer-instructions.ts

@@ -7,6 +7,7 @@ import { engineChores, REVIEW_FIXER, setupFiles } from './common-instructions'
 import {
     caseLimitOf,
     featureMapPath,
+    hasJunitCommand,
     isFeatureMapFolder,
     slowTestCommands,
     testCommands,
@@ -58,6 +59,18 @@ const testHelperClause = ({ config }: { config: EngineConfig }): string => {
         : `, test helpers only tests use, such as fakes and fixtures (${patterns.join(', ')})`
 }
 
+/** How to write a Swift test the engine can count (#672), or nothing without a junit command. */
+const swiftTestLine = ({ config }: { config: EngineConfig }): string =>
+    hasJunitCommand({ config })
+        ? "- In a .swift test file, write each test as a Swift Testing `@Test func` or an XCTest `func testSomething()`, and call `#expect`, `#require` or an `XCTAssert` function directly in its body: the engine counts them in the test's source, not as it runs.\n"
+        : ''
+
+/** A Swift test's full name (#672), or nothing without a junit command. */
+const swiftNameLine = ({ config }: { config: EngineConfig }): string =>
+    hasJunitCommand({ config })
+        ? '\n- For a .swift test, "name" is its type names and its function, joined by " > ": `RankingTests > addsMovie()` for a Swift Testing test (keeping argument labels, such as `ranks(score:)`), and `RankingXCTests > testAddsMovie` for an XCTest one. A @Test\'s display name is not part of it.'
+        : ''
+
 export const TEST_WRITER = ({
     config,
 }: {
@@ -72,11 +85,11 @@ You write the failing tests for ONE ticket, before any code exists.
 ${featureMapLines({ config })}- Every acceptance criterion needs at least one test, and at most ${MAX_TESTS_PER_CRITERION}: write the fewest tests that prove it. Old tests must keep passing.
 - Map every test you add. The red check refuses a new test your criterion mapping doesn't name.
 - Give every test a plain string-literal name (no test.each, no template names), so the engine can find each one before the module exists.
-
+${swiftTestLine({ config })}
 Your result (structured output):
 - outcome: "tests_written", or "nothing_new_to_test" if the ticket truly changes no behavior (a refactor), or "already_done" if the ticket's work is already on the base branch, or "needs_setup_change" if the tests can't work without a change to a test setup file${setupFiles({ config })} (you may never change one): say which file and why in "setup_change", and the user makes the change.
 - Answer "already_done" only when EVERY acceptance criterion is already met on the base branch and already has a test that checks it. Look with \`git log\` and \`git show\`, and read the code and tests. Then write no tests, and give your evidence: in "done_by", the commits that did the work, as { sha, title }; in "criteria", the existing tests that cover each criterion. The engine checks this evidence: each commit must be on the base branch, and each test must exist and pass there. If even one criterion is not met, or not tested, write the tests instead.
-- criteria: for EACH criterion id (AC1, AC2, ...), the tests that check it, as { file, name }. "name" is the full name bun prints: describe names and the test name joined by " > ".
+- criteria: for EACH criterion id (AC1, AC2, ...), the tests that check it, as { file, name }. "name" is the full name bun prints: describe names and the test name joined by " > ".${swiftNameLine({ config })}
 ${environmentLine({ check: 'the red check' })}
 - done_by: empty, unless the outcome is "already_done".
 - finding_responses: empty, unless your prompt gives you ticket review findings (see below).

package/engine/cli/setup-config.ts

@@ -0,0 +1,215 @@
+/**
+ * `luca setup`'s config side: guessing the checks from `package.json`,
+ * finding what is at `.luca/config.json`, writing a starting one, and the
+ * done and to-do lines for a config that loads.
+ */
+import { mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { z } from 'zod'
+
+import {
+    ENGINE_CONFIG_FILE,
+    EngineConfigSchema,
+    givesPerTestResults,
+    isBunTestCommand,
+    MuninnConfigSchema,
+    testCommands,
+    type EngineConfig,
+    type TestCommand,
+} from '../config/engine-config'
+
+/**
+ * The top-level and `muninn` keys of a new-style engine config, from its
+ * schema. A config with any other key (such as old Luca's `lucaVersion`) is
+ * an old-Luca config.
+ */
+const NEW_CONFIG_KEYS = new Set(Object.keys(EngineConfigSchema.shape))
+const NEW_MUNINN_KEYS = new Set(Object.keys(MuninnConfigSchema.shape))
+
+const PackageJsonSchema = z.looseObject({
+    scripts: z.record(z.string(), z.string()).default({}),
+})
+
+export const errorText = (error: unknown): string =>
+    error instanceof Error ? error.message : String(error)
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/**
+ * The checks guessed from `package.json` scripts: `test` and `test:*`
+ * become test commands (a script that is a `bun test` command runs as
+ * written and is bun-readable; the rest run with `bun run` and are
+ * pass-or-fail), `type-check` or `typecheck` becomes types, and `lint`
+ * becomes lint. Pure.
+ *
+ * @example
+ * guessChecks({ scripts: { test: 'bun test', 'test:workers': 'vitest run', lint: 'eslint .' } })
+ * // { test: [{ run: 'bun test', results: 'bun' }, { run: 'bun run test:workers', results: 'pass_fail' }], lint: 'bun run lint' }
+ */
+export const guessChecks = ({
+    scripts,
+}: {
+    scripts: Record<string, string>
+}): EngineConfig['checks'] => {
+    const test: Pick<TestCommand, 'run' | 'results'>[] = Object.entries(scripts)
+        .filter(([name]) => name === 'test' || name.startsWith('test:'))
+        .toSorted(([a], [b]) => Number(b === 'test') - Number(a === 'test'))
+        .map(([name, script]) =>
+            isBunTestCommand(script)
+                ? { run: script.trim(), results: 'bun' }
+                : { run: `bun run ${name}`, results: 'pass_fail' }
+        )
+    const types = ['type-check', 'typecheck'].find(
+        (name) => scripts[name] !== undefined
+    )
+    return {
+        ...(test.length === 0 ? {} : { test }),
+        ...(types === undefined ? {} : { types: `bun run ${types}` }),
+        ...(scripts.lint === undefined ? {} : { lint: 'bun run lint' }),
+    }
+}
+
+/** The repo's `package.json` scripts; none when it has no readable one. */
+export const readScripts = async ({
+    repo,
+}: {
+    repo: string
+}): Promise<Record<string, string>> => {
+    const file = Bun.file(join(repo, 'package.json'))
+    if (!(await file.exists())) return {}
+    try {
+        const parsed = PackageJsonSchema.safeParse(
+            JSON.parse(await file.text())
+        )
+        return parsed.success ? parsed.data.scripts : {}
+    } catch {
+        return {}
+    }
+}
+
+/** What is at `.luca/config.json` before setup touches it. */
+export type FoundConfig =
+    | { kind: 'missing' }
+    | { kind: 'broken'; error: string }
+    | { kind: 'old'; raw: Record<string, unknown> }
+    | { kind: 'new' }
+
+export const findConfig = async ({
+    repo,
+}: {
+    repo: string
+}): Promise<FoundConfig> => {
+    const file = Bun.file(join(repo, ENGINE_CONFIG_FILE))
+    if (!(await file.exists())) return { kind: 'missing' }
+    let raw: unknown
+    try {
+        raw = JSON.parse(await file.text())
+    } catch (error) {
+        return { kind: 'broken', error: `it isn't JSON: ${errorText(error)}` }
+    }
+    if (!isRecord(raw)) {
+        return { kind: 'broken', error: "it isn't a JSON object" }
+    }
+    const muninn = raw.muninn
+    const old =
+        Object.keys(raw).some((key) => !NEW_CONFIG_KEYS.has(key)) ||
+        (isRecord(muninn) &&
+            Object.keys(muninn).some((key) => !NEW_MUNINN_KEYS.has(key)))
+    return old ? { kind: 'old', raw } : { kind: 'new' }
+}
+
+/** A starting config: the guessed checks, and the vault if there is one. */
+export const startingConfig = ({
+    scripts,
+    vault,
+}: {
+    scripts: Record<string, string>
+    vault: string | null
+}): Record<string, unknown> => ({
+    checks: guessChecks({ scripts }),
+    ...(vault === null ? {} : { muninn: { vault } }),
+})
+
+const vaultName = (vault: unknown): string | null =>
+    typeof vault === 'string' && vault.trim() !== '' ? vault : null
+
+/**
+ * The vault an old-Luca config names in `muninn.vault`, or else in an older
+ * top-level `vault`, if any.
+ */
+export const oldVault = ({
+    raw,
+}: {
+    raw: Record<string, unknown>
+}): string | null =>
+    vaultName(isRecord(raw.muninn) ? raw.muninn.vault : undefined) ??
+    vaultName(raw.vault)
+
+/**
+ * The `name` part of a GitHub `owner/name`, a new repo's vault. Pure.
+ *
+ * @example
+ * repoName({ github_repo: 'asibilia/tmnb' }) // 'tmnb'
+ */
+export const repoName = ({
+    github_repo,
+}: {
+    github_repo: string | null
+}): string | null => vaultName(github_repo?.split('/').at(-1)?.trim() ?? null)
+
+export const writeConfig = async ({
+    repo,
+    config,
+}: {
+    repo: string
+    config: Record<string, unknown>
+}) => {
+    const path = join(repo, ENGINE_CONFIG_FILE)
+    await mkdir(dirname(path), { recursive: true })
+    await Bun.write(path, `${JSON.stringify(config, null, 4)}\n`)
+}
+
+const READABLE: Record<TestCommand['results'], string> = {
+    bun: 'bun-readable',
+    junit: 'junit-readable',
+    pass_fail: 'pass or fail',
+}
+
+const describeTest = ({ run, results }: TestCommand): string =>
+    `\`${run}\` (${READABLE[results]})`
+
+/** The done and to-do lines for a config that loads. */
+export const reportConfig = ({
+    config,
+}: {
+    config: EngineConfig
+}): { done: string[]; todo: string[] } => {
+    const tests = testCommands({ config })
+    const done: string[] = []
+    const todo: string[] = []
+    if (tests.length === 0) {
+        todo.push(
+            `Add a test command to \`checks.test\` in ${ENGINE_CONFIG_FILE}. Intake refuses a run without one.`
+        )
+    } else {
+        done.push(`Test commands: ${tests.map(describeTest).join(', ')}`)
+        if (!tests.some(({ results }) => givesPerTestResults(results))) {
+            todo.push(
+                `No test command gives per-test results, so only refactor tickets can run. Add a \`bun test\` command, or one with \`"results": "junit"\`, to \`checks.test\` in ${ENGINE_CONFIG_FILE}.`
+            )
+        }
+    }
+    for (const kind of ['types', 'lint'] as const) {
+        const command = config.checks[kind]
+        if (command === undefined) {
+            todo.push(
+                `No ${kind} check. Add \`checks.${kind}\` to ${ENGINE_CONFIG_FILE} if the repo has one.`
+            )
+        } else {
+            done.push(`The ${kind} check: \`${command}\``)
+        }
+    }
+    return { done, todo }
+}

package/engine/cli/setup-junit-check.ts

@@ -0,0 +1,134 @@
+/**
+ * Doctor's `junit` check (#668): each junit test command that runs `swift
+ * test` should pass `--parallel` (without it XCTest writes no JUnit file)
+ * and list both of SwiftPM's files in `junit_path`.
+ */
+import { stat } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+import uniq from 'lodash/uniq'
+
+import { ok, warning, type Found } from './doctor-checks'
+import { readScripts } from './setup-config'
+
+import {
+    ENGINE_CONFIG_FILE,
+    junitCommands,
+    type EngineConfig,
+} from '../config/engine-config'
+import { insideWorktree } from '../guards/write-rules'
+
+/** The shells a script may start its file with. */
+const SHELLS = new Set(['bash', 'sh', 'zsh'])
+
+const SWIFT_TESTING_SUFFIX = '-swift-testing.xml'
+
+/**
+ * The text of the repo file at `path`, or `null` when there is no such file
+ * or `path` leaves the repo (with `..`, or an absolute path outside it).
+ */
+const fileText = async ({
+    repo,
+    path,
+}: {
+    repo: string
+    path: string
+}): Promise<string | null> => {
+    const inner = insideWorktree({ worktree: repo, path })
+    if (inner === null) return null
+    const full = join(repo, inner)
+    try {
+        return (await stat(full)).isFile() ? await Bun.file(full).text() : null
+    } catch {
+        return null
+    }
+}
+
+/**
+ * The texts a command runs: itself; for `bun run <script>`, that script in
+ * the root `package.json`; and the repo file that script starts, directly
+ * or after `bash`, `sh` or `zsh`.
+ */
+const textsOf = async ({
+    repo,
+    run,
+    scripts,
+}: {
+    repo: string
+    run: string
+    scripts: Record<string, string>
+}): Promise<string[]> => {
+    const name = /^bun\s+run\s+(\S+)/.exec(run.trim())?.[1]
+    const script = name === undefined ? undefined : scripts[name]
+    if (script === undefined) return [run]
+    const words = script.trim().split(/\s+/)
+    const first = words[0] ?? ''
+    const path = SHELLS.has(first) ? words[1] : first
+    const file = path === undefined ? null : await fileText({ repo, path })
+    return [run, script, ...(file === null ? [] : [file])]
+}
+
+/**
+ * The other file of SwiftPM's pair for a `junit_path` entry, in the same
+ * folder: `core.xml` and `core-swift-testing.xml` go together. `null` for
+ * a path that isn't an `.xml` file.
+ */
+const partnerOf = (path: string): string | null => {
+    const name = basename(path)
+    const partner = name.endsWith(SWIFT_TESTING_SUFFIX)
+        ? `${name.slice(0, -SWIFT_TESTING_SUFFIX.length)}.xml`
+        : name.endsWith('.xml')
+          ? `${name.slice(0, -'.xml'.length)}${SWIFT_TESTING_SUFFIX}`
+          : null
+    if (partner === null) return null
+    const folder = dirname(path)
+    return folder === '.' ? partner : `${folder}/${partner}`
+}
+
+/**
+ * The `junit` check for a config with junit commands: a warning for each
+ * one that runs `swift test` without `--parallel`, and for each of
+ * SwiftPM's files its `junit_path` leaves out, made into one; else OK.
+ */
+export const checkJunit = async ({
+    repo,
+    config,
+}: {
+    repo: string
+    config: EngineConfig
+}): Promise<Found> => {
+    const scripts = await readScripts({ repo })
+    const found: { detail: string; fix: string }[] = []
+    for (const { run, junit_path } of junitCommands({ config })) {
+        const texts = await textsOf({ repo, run, scripts })
+        if (!texts.some((text) => text.includes('swift test'))) continue
+        if (!texts.some((text) => text.includes('--parallel'))) {
+            found.push({
+                detail: `\`${run}\` runs swift test without --parallel, so XCTest writes no JUnit file and its results can't be read.`,
+                fix: 'Add --parallel to its swift test command.',
+            })
+        }
+        const listed = new Set(junit_path)
+        const missing = uniq(
+            junit_path.flatMap((path) => {
+                const partner = partnerOf(path)
+                return partner === null || listed.has(partner) ? [] : [partner]
+            })
+        )
+        for (const path of missing) {
+            found.push({
+                detail: `\`${run}\` runs swift test, but its junit_path doesn't list ${path}.`,
+                fix: `Add it to junit_path in ${ENGINE_CONFIG_FILE}: swift test writes XCTest results to core.xml and Swift Testing results to core-swift-testing.xml.`,
+            })
+        }
+    }
+    if (found.length === 0) {
+        return ok(
+            'Each junit test command that runs swift test uses --parallel and lists both of its JUnit files'
+        )
+    }
+    return warning({
+        detail: found.map(({ detail }) => detail).join(' '),
+        fix: found.map(({ fix }) => fix).join(' '),
+    })
+}