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

package/engine/cli/luca-run.ts

@@ -7,9 +7,13 @@
  *       --run-id <id> --board-plugin luca-board      (token in $LUCA_BOARD_TOKEN)
  *
  * A real run builds with real Claude agents (`createClaudeLauncher`: Claude
- * Opus 5.5, every guard on, paid by your Claude plan) and asks Jev in shadow
- * mode (`createTypeSafeJev`, which reads `TYPESAFE_API_KEY`; with no key each
- * ask is journaled as `missing_key` and the run goes on). Memory (#370) is
+ * Opus 5.5, every guard on, paid by your Claude plan) and asks the decision
+ * model, Cloudflare's Clef, in shadow mode (#534). Its credentials,
+ * `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, come from Luca's own
+ * env file, `~/.config/luca/.env` (or `$XDG_CONFIG_HOME/luca/.env`), with
+ * the process env winning key by key; never from the repo's `.env`. With
+ * none, the decision model is off for the run: one line and one
+ * `decision_model_off` record, and no asks. Memory (#370) is
  * MuninnDB over MCP, found through `LUCA_MUNINN_URL` and `LUCA_MUNINN_TOKEN`
  * or Claude Code's `mcpServers.muninn` in `~/.claude.json`; with neither,
  * the run goes on without memory.
@@ -26,6 +30,8 @@
  */
 import { homedir } from 'node:os'
 
+import { defaultRegistryPath, goingRuns } from './going-runs'
+import { listProcesses } from './live-runs'
 import { parseRunArgs, type RunArgs } from './run-args'
 import {
     DEMO_TURN_DELAY_MS,
@@ -39,7 +45,7 @@ import {
 import { createClaudeLauncher } from '../agents/claude-launcher'
 import { createBoardSync, type BoardSync } from '../board/board-sync'
 import { createPaseoBoardLink } from '../board/paseo-board-link'
-import { createTypeSafeJev } from '../jev/jev-client'
+import { loadDecisionModelCredentials } from '../jev/decision-model-credentials'
 import { defaultRunsDir } from '../journal/journal'
 import {
     defaultSharedReadingsPath,
@@ -76,6 +82,28 @@ const memoryOf = async (): Promise<MemoryDeps | undefined> => {
     return { client: createMuninnMcpClient({ settings: found.settings }) }
 }
 
+/** The decision model's setup: its credentials from Luca's own env file. */
+const decisionModelSetup = async () => ({
+    credentials: await loadDecisionModelCredentials({
+        env: process.env,
+        home: homedir(),
+    }),
+})
+
+/**
+ * The unfinished runs on this computer, for the repo wait (#615): every
+ * journal in the runs folder and the board's registry, checked with `ps`.
+ */
+const goingRunsNow = () =>
+    goingRuns({
+        runs_dir: defaultRunsDir(),
+        registry_path: defaultRegistryPath({
+            env: process.env,
+            home_dir: homedir(),
+        }),
+        list_processes: listProcesses,
+    })
+
 /**
  * The usage line (#434): the `luca-board` plugin's lines, and the readings
  * every run shares, both in Luca's state folder.
@@ -117,17 +145,22 @@ const run = async ({
             runs_dir: defaultRunsDir(),
             repo: args.repo,
             tracker: async ({ repo }) =>
-                createGitHubTracker({ repo: await githubRepoOf({ repo }) }),
+                createGitHubTracker({
+                    repo: await githubRepoOf({ repo }),
+                    log,
+                }),
             launcher: createClaudeLauncher({}),
-            jev: { client: createTypeSafeJev() },
+            decision_model: await decisionModelSetup(),
             memory: await memoryOf(),
             usage: usageLine(),
+            going_runs: goingRunsNow,
             board,
             log,
         })
     }
     const tracker = createGitHubTracker({
         repo: await githubRepoOf({ repo: args.repo }),
+        log,
     })
     return runSpec({
         spec_number: args.spec_number,
@@ -137,9 +170,11 @@ const run = async ({
         runs_dir: defaultRunsDir(),
         tracker,
         launcher: createClaudeLauncher({}),
-        jev: { client: createTypeSafeJev() },
+        decision_model: await decisionModelSetup(),
         memory: await memoryOf(),
         usage: usageLine(),
+        going_runs: goingRunsNow,
+        alongside: args.alongside === true,
         board,
         log,
     })

package/engine/cli/luca-skills.ts

@@ -0,0 +1,183 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import type { StepEnd } from './board-in-paseo'
+import { reason } from './doctor-checks'
+
+/**
+ * Luca's own Claude Code skills, such as `/luca-unstick` (#504) and
+ * `/luca-retro` (#514). They ship in the package's `skills/` folder, next
+ * to `engine/` and `board/` (`packages/engine/skills/` in the repo). `luca
+ * init` and `luca upgrade` copy them to `~/.claude/skills/<skill>/`, so
+ * they work in any repo and any Paseo chat, and `luca doctor` checks the
+ * copy is the one the installed Luca ships (`luca doctor --fix` copies it
+ * again).
+ *
+ * Which skills there are comes from that folder, not a list in the code
+ * (#529): every folder in it with a `SKILL.md`. So a skill new in a
+ * release is copied and checked even by code from before it.
+ *
+ * A copy writes every file the skill ships (not its tests), over Luca's own
+ * earlier copy. It never deletes, and never touches other skills.
+ */
+
+/** Test files stay in the repo: they aren't part of a skill. */
+const isTestFile = (path: string) => /\.test\.[cm]?[jt]sx?$/.test(path)
+
+/** Where Claude Code finds a user's own skills. */
+export const claudeSkillsDir = ({ home }: { home: string }): string =>
+    join(home, '.claude', 'skills')
+
+/**
+ * Luca's own skills in `skills_dir`, by folder name, sorted: each folder
+ * with a `SKILL.md`. None when the folder is missing.
+ *
+ * @example
+ * await lucaSkills({ skills_dir }) // ['luca-retro', 'luca-unstick']
+ */
+export const lucaSkills = async ({
+    skills_dir,
+}: {
+    skills_dir: string
+}): Promise<string[]> => {
+    try {
+        const manifests = await Array.fromAsync(
+            new Bun.Glob('*/SKILL.md').scan({
+                cwd: skills_dir,
+                onlyFiles: true,
+            })
+        )
+        return manifests.map((manifest) => dirname(manifest)).toSorted()
+    } catch {
+        return []
+    }
+}
+
+/**
+ * The files one skill ships, relative to its folder in `skills_dir`,
+ * sorted: every file but tests. None when the folder is missing.
+ *
+ * @example
+ * await skillFiles({ skills_dir, skill: 'luca-unstick' }) // ['SKILL.md', 'scripts/stuck-summary.ts']
+ */
+export const skillFiles = async ({
+    skills_dir,
+    skill,
+}: {
+    skills_dir: string
+    skill: string
+}): Promise<string[]> => {
+    try {
+        const files = await Array.fromAsync(
+            new Bun.Glob('**/*').scan({
+                cwd: join(skills_dir, skill),
+                dot: true,
+                onlyFiles: true,
+            })
+        )
+        return files.filter((file) => !isTestFile(file)).toSorted()
+    } catch {
+        return []
+    }
+}
+
+/** How one installed skill differs from the one Luca ships. */
+export type SkillDrift = {
+    skill: string
+    /** Shipped files the installed copy lacks. */
+    missing: string[]
+    /** Shipped files whose installed copy has other content. */
+    changed: string[]
+}
+
+/**
+ * How each of Luca's skills in `~/.claude/skills` differs from the ones in
+ * `skills_dir`; a skill that matches has empty lists. None when
+ * `skills_dir` has no skills. Read-only.
+ */
+export const skillDrift = async ({
+    home,
+    skills_dir,
+}: {
+    home: string
+    skills_dir: string
+}): Promise<SkillDrift[]> => {
+    const drift: SkillDrift[] = []
+    for (const skill of await lucaSkills({ skills_dir })) {
+        const files = await skillFiles({ skills_dir, skill })
+        const missing: string[] = []
+        const changed: string[] = []
+        for (const file of files) {
+            const installed = Bun.file(
+                join(claudeSkillsDir({ home }), skill, file)
+            )
+            if (!(await installed.exists())) {
+                missing.push(file)
+                continue
+            }
+            const shipped = Bun.file(join(skills_dir, skill, file))
+            if ((await installed.text()) !== (await shipped.text())) {
+                changed.push(file)
+            }
+        }
+        drift.push({ skill, missing, changed })
+    }
+    return drift
+}
+
+/**
+ * Copies Luca's skills from `skills_dir` into `~/.claude/skills`, over
+ * Luca's own earlier copy: each shipped file whose installed copy is
+ * missing or differs is written. Logs one line after `prefix`. Never
+ * throws.
+ *
+ * @example
+ * await installLucaSkills({ home: homedir(), skills_dir, prefix: '[luca init]', log: console.log })
+ * // [luca init] Luca's skills: installed /luca-retro, /luca-unstick in ~/.claude/skills
+ */
+export const installLucaSkills = async ({
+    home,
+    skills_dir,
+    prefix,
+    log,
+}: {
+    home: string
+    skills_dir: string
+    prefix: string
+    log: (line: string) => void
+}): Promise<StepEnd> => {
+    const say = ({ message, ok }: StepEnd): StepEnd => {
+        log(message)
+        return { ok, message }
+    }
+    try {
+        const drift = await skillDrift({ home, skills_dir })
+        if (drift.length === 0) {
+            return say({
+                message: `${prefix} Luca's skills: Luca's folder ${skills_dir} has none. Reinstall Luca.`,
+                ok: false,
+            })
+        }
+        const written: string[] = []
+        for (const { skill, missing, changed } of drift) {
+            for (const file of [...missing, ...changed]) {
+                const target = join(claudeSkillsDir({ home }), skill, file)
+                await mkdir(dirname(target), { recursive: true })
+                await Bun.write(target, Bun.file(join(skills_dir, skill, file)))
+            }
+            if (missing.length + changed.length > 0) written.push(skill)
+        }
+        return say({
+            message:
+                written.length === 0
+                    ? `${prefix} Luca's skills: up to date`
+                    : `${prefix} Luca's skills: installed ${written.map((skill) => `/${skill}`).join(', ')} in ${claudeSkillsDir({ home })}`,
+            ok: true,
+        })
+    } catch (error) {
+        return say({
+            message: `${prefix} Luca's skills: ${reason(error)}`,
+            ok: false,
+        })
+    }
+}

package/engine/cli/luca.ts

@@ -9,6 +9,8 @@
  *   luca upgrade [--to <version>]  moves to another version of Luca
  *   luca doctor [--fix]            checks this computer and repo; --fix
  *                                  fixes what's safe
+ *   luca models                    scores each routed role's model from
+ *                                  this repo's runs
  *   luca hook <anything>           does nothing, quietly
  *
  * `luca hook` is for old Luca (v13), whose global Claude Code hook runs
@@ -26,7 +28,8 @@ Commands:
                             Set up this computer for Luca (once), then the repo you're in
   setup [--base <branch>]   Get the repo in this folder ready for Luca
   upgrade [--to <version>]  Move to the newest Luca on your channel, or to <version>
-  doctor [--fix]            Check this computer and repo; --fix fixes what's safe`
+  doctor [--fix]            Check this computer and repo; --fix fixes what's safe
+  models                    Score each routed role's model from this repo's runs`
 
 const main = async (): Promise<number> => {
     const [command, ...rest] = Bun.argv.slice(2)
@@ -49,6 +52,10 @@ const main = async (): Promise<number> => {
             const { doctorCommand } = await import('./doctor-command')
             return doctorCommand({ argv: rest })
         }
+        case 'models': {
+            const { modelsCommand } = await import('./models-command')
+            return modelsCommand({ argv: rest })
+        }
         case '--help':
         case '-h':
         case 'help':

package/engine/cli/models-command.ts

@@ -0,0 +1,119 @@
+/**
+ * `luca models`: scores each routed role's model from the ticket review's
+ * findings over this repo's runs, and prints the report (#605):
+ *
+ *   luca models
+ *
+ * It only reads: it never writes config or journals. A run is this repo's
+ * when its `run_started` repo is the main checkout or git top folder of the
+ * current folder. Exits 0, 2 on bad flags.
+ */
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
+import { basename, dirname, resolve } from 'node:path'
+
+import { defaultRunsDir, readRecords, runJournalPath } from '../journal/journal'
+import type { JournalRecord } from '../journal/journal-record'
+import { formatModelReport, scoreModels } from '../models/model-score'
+
+/** `luca models`'s usage line. */
+export const MODELS_USAGE = 'Usage: luca models'
+
+/** A path with its symlinks followed, or made absolute when it's gone. */
+const realPath = (path: string): string => {
+    try {
+        return realpathSync(path)
+    } catch {
+        return resolve(path)
+    }
+}
+
+/**
+ * The repos a run started from `cwd` may name, real paths: the main
+ * checkout (a worktree's too), then the git top folder. Outside git, `cwd`.
+ */
+const currentRepos = ({ cwd }: { cwd: string }): string[] => {
+    const git = (...args: string[]) => {
+        const out = Bun.spawnSync(['git', '-C', cwd, ...args])
+        const said = out.stdout.toString().trim()
+        return out.exitCode === 0 && said !== '' ? said : null
+    }
+    const top = git('rev-parse', '--show-toplevel')
+    const common = git(
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-common-dir'
+    )
+    const main =
+        common !== null && basename(common) === '.git' ? dirname(common) : null
+    return [
+        ...new Set(
+            [main, top ?? cwd]
+                .filter((repo) => repo !== null)
+                .map((repo) => realPath(repo))
+        ),
+    ]
+}
+
+/**
+ * The records of every run in `runs_dir` that started in one of `repos`,
+ * oldest run id first. A journal that can't be read is left out, with a
+ * line on `warn`.
+ */
+const repoRuns = ({
+    runs_dir,
+    repos,
+    warn,
+}: {
+    runs_dir: string
+    repos: string[]
+    warn: (line: string) => void
+}): JournalRecord[][] => {
+    if (!existsSync(runs_dir)) return []
+    const want = new Set(repos)
+    return readdirSync(runs_dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map(({ name }) => name)
+        .toSorted()
+        .flatMap((run_id) => {
+            let records: JournalRecord[]
+            try {
+                records = readRecords({
+                    file: runJournalPath({ runs_dir, run_id }),
+                })
+            } catch (error) {
+                warn(
+                    `Left out run ${run_id}: ${error instanceof Error ? error.message : String(error)}`
+                )
+                return []
+            }
+            const [first] = records
+            return first?.kind === 'run_started' &&
+                first.content.repo !== null &&
+                want.has(realPath(first.content.repo))
+                ? [records]
+                : []
+        })
+}
+
+/** Runs `luca models` with the flags after `models`; returns the exit code. */
+export const modelsCommand = ({ argv }: { argv: string[] }): number => {
+    if (argv.length > 0) {
+        console.error(MODELS_USAGE)
+        return 2
+    }
+    const runs_dir = defaultRunsDir()
+    const repos = currentRepos({ cwd: process.cwd() })
+    const runs = repoRuns({
+        runs_dir,
+        repos,
+        warn: (line) => {
+            console.error(`[luca models] ${line}`)
+        },
+    })
+    if (runs.length === 0) {
+        console.log(`No Luca runs of ${repos.join(' or ')} in ${runs_dir}.`)
+        return 0
+    }
+    console.log(formatModelReport({ report: scoreModels({ runs }) }))
+    return 0
+}

package/engine/cli/read-run.ts

@@ -0,0 +1,81 @@
+/**
+ * Reading a run's journal to go on from it: the records of a run in the runs
+ * folder (`readRun`), and its `run_started` (`readRunStart`, `RunStart`).
+ */
+import { existsSync } from 'node:fs'
+
+import { errorText } from './run-end'
+
+import { createJournal, runJournalPath } from '../journal/journal'
+import type { JournalRecord } from '../journal/journal-record'
+
+/** What a run's `run_started` says: its spec, base branch, repo, and time. */
+export type RunStart = {
+    spec_number: number
+    base_branch: string
+    /** `null` in journals from before the repo was kept. */
+    repo: string | null
+    /** When `run_started` was journaled. */
+    started_at: string
+}
+
+/**
+ * The records of run `run_id`, or why there are none to go on from: no
+ * journal, an empty one, or one that cannot be read. Never makes the run's
+ * folder.
+ */
+export const readRun = ({
+    runs_dir,
+    run_id,
+}: {
+    runs_dir: string
+    run_id: string
+}): { ok: true; records: JournalRecord[] } | { ok: false; error: string } => {
+    const file = runJournalPath({ runs_dir, run_id })
+    if (!existsSync(file)) {
+        return { ok: false, error: `No run ${run_id}: there is no ${file}.` }
+    }
+    try {
+        const records = createJournal({ file }).read()
+        return records.length === 0
+            ? {
+                  ok: false,
+                  error: `Run ${run_id} has an empty journal (${file}), so there is nothing to go on from; start a new run with --spec.`,
+              }
+            : { ok: true, records }
+    } catch (error) {
+        return { ok: false, error: errorText(error) }
+    }
+}
+
+/**
+ * Reads run `run_id`'s `run_started`: the spec, base branch, and repo a
+ * resume goes on with. An error when the run has no journal, an empty one,
+ * or one that does not start with `run_started`.
+ *
+ * @example
+ * const start = readRunStart({ runs_dir: defaultRunsDir(), run_id })
+ * if (start.ok) console.log(start.start.spec_number)
+ */
+export const readRunStart = ({
+    runs_dir,
+    run_id,
+}: {
+    runs_dir: string
+    run_id: string
+}): { ok: true; start: RunStart } | { ok: false; error: string } => {
+    const read = readRun({ runs_dir, run_id })
+    if (!read.ok) return read
+    const [first] = read.records
+    if (first?.kind !== 'run_started') {
+        return {
+            ok: false,
+            error: `Run ${run_id}'s journal does not start with run_started, so it is not a run.`,
+        }
+    }
+    const { spec_number, base_branch, repo } = first.content
+    return {
+        ok: true,
+        start: { spec_number, base_branch, repo, started_at: first.time },
+    }
+}

package/engine/cli/run-args.ts

@@ -10,7 +10,7 @@ export const BOARD_TOKEN_ENV = 'LUCA_BOARD_TOKEN'
 
 /** How to call `luca-run`, shown with every argument error. */
 export const RUN_USAGE = `Usage:
-  luca-run --spec <n> [--repo <path>] [--run-id <id>] [--base <branch>] [--board-plugin <id>]
+  luca-run --spec <n> [--repo <path>] [--run-id <id>] [--base <branch>] [--alongside] [--board-plugin <id>]
   luca-run --demo [--run-id <id>] [--board-plugin <id>]
   luca-run --resume <run-id> [--repo <path>] [--board-plugin <id>]
   luca-run --unfinished
@@ -26,6 +26,8 @@ export const RUN_USAGE = `Usage:
                         (for --resume, to the repo the run started in).
   --run-id <id>         The run's id and folder name. Defaults to a new one.
   --base <branch>       The branch the run starts from. Defaults to main.
+  --alongside           Start now, even while an earlier run on the repo is
+                        going. Without it, the run waits for that run first.
   --board-plugin <id>   Send the journal to this Paseo board plugin; the
                         per-run token comes from $${BOARD_TOKEN_ENV}.`
 
@@ -67,6 +69,7 @@ const resumeArgsSchema = ({ cwd }: { cwd: string }) =>
             demo: z.undefined('Give only one of --resume or --demo.'),
             run_id: z.undefined('--resume <run-id> is the run id.'),
             base: z.undefined('--resume takes the base from the journal.'),
+            alongside: z.undefined('--alongside is for a new run (--spec).'),
         })
         .refine(({ board_plugin, token }) => board_plugin === null || token, {
             message: BOARD_TOKEN_MESSAGE,
@@ -91,6 +94,7 @@ const unfinishedArgsSchema = z
         repo: z.undefined(UNFINISHED_ALONE),
         run_id: z.undefined(UNFINISHED_ALONE),
         base: z.undefined(UNFINISHED_ALONE),
+        alongside: z.undefined(UNFINISHED_ALONE),
         board_plugin: z.undefined(UNFINISHED_ALONE),
     })
     .transform((): RunArgs => ({ mode: 'unfinished' }))
@@ -107,26 +111,42 @@ const runArgsSchema = ({ cwd }: { cwd: string }) =>
                 .transform((path) => resolve(cwd, path)),
             run_id: RunIdSchema.default(() => makeRunId()),
             base: z.string().min(1).nullable().default(null),
+            alongside: z.boolean().default(false),
             board_plugin: z.string().min(1).nullable().default(null),
             token: z.string().nullable().default(null),
         })
         .refine(({ spec, demo }) => (spec === undefined) === demo, {
             message: 'Give exactly one of --spec <n> or --demo.',
         })
+        .refine(({ demo, alongside }) => !(demo && alongside), {
+            message: '--alongside is for a run of a spec (--spec).',
+        })
         .refine(({ board_plugin, token }) => board_plugin === null || token, {
             message: BOARD_TOKEN_MESSAGE,
         })
         .transform(
-            ({ spec, repo, run_id, base, board_plugin, token }): RunArgs => {
+            ({
+                spec,
+                repo,
+                run_id,
+                base,
+                alongside,
+                board_plugin,
+                token,
+            }): RunArgs => {
                 const common = {
                     repo,
                     run_id,
                     base_branch: base,
                     board: boardOf({ board_plugin, token }),
                 }
-                return spec === undefined
-                    ? { mode: 'demo', ...common }
-                    : { mode: 'spec', spec_number: spec, ...common }
+                if (spec === undefined) return { mode: 'demo', ...common }
+                return {
+                    mode: 'spec',
+                    spec_number: spec,
+                    ...common,
+                    ...(alongside ? { alongside: true } : {}),
+                }
             }
         )
 
@@ -142,7 +162,12 @@ type RunArgsCommon = {
 
 /** What `luca-run` was asked to do. */
 export type RunArgs =
-    | (RunArgsCommon & { mode: 'spec'; spec_number: number })
+    | (RunArgsCommon & {
+          mode: 'spec'
+          spec_number: number
+          /** Skip the repo wait (`--alongside`); left out, the run waits. */
+          alongside?: true
+      })
     | (RunArgsCommon & { mode: 'demo' })
     | {
           mode: 'resume'
@@ -189,6 +214,7 @@ export const parseRunArgs = ({
                 repo: { type: 'string' },
                 'run-id': { type: 'string' },
                 base: { type: 'string' },
+                alongside: { type: 'boolean' },
                 'board-plugin': { type: 'string' },
             },
         }).values
@@ -210,6 +236,7 @@ export const parseRunArgs = ({
         repo: values.repo,
         run_id: values['run-id'],
         base: values.base,
+        alongside: values.alongside,
         board_plugin: values['board-plugin'],
         token: env[BOARD_TOKEN_ENV],
     })