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

package/engine/cli/unfinished-runs.ts

@@ -0,0 +1,122 @@
+/**
+ * The runs in the runs folder that are not over, and whether Paseo may
+ * restart each one (#375): `unfinishedRuns`, `restartableRuns`, and the shape
+ * `luca-run --unfinished` prints.
+ */
+import { existsSync, readdirSync } from 'node:fs'
+
+import { z } from 'zod'
+
+import { readRun } from './read-run'
+
+import { decide } from '../core/decide'
+import { STOP_ACTIONS } from '../core/execute'
+import type { JournalRecord } from '../journal/journal-record'
+
+/**
+ * The ids of the runs in `runs_dir` that are not over: runs whose journal's
+ * next action (by the decision step) is not a stop (`done` or
+ * `invalid_journal`), such as a run that crashed, was killed, or waits for a
+ * reply. Folders with no journal, an empty one, or one that cannot be read
+ * are left out. Sorted, so oldest first for made-up run ids. Paseo can
+ * `resumeRun` each one when it starts (#375).
+ *
+ * @example
+ * for (const run_id of unfinishedRuns({ runs_dir: defaultRunsDir() })) console.log(run_id)
+ */
+export const unfinishedRuns = ({
+    runs_dir,
+}: {
+    runs_dir: string
+}): string[] => {
+    if (!existsSync(runs_dir)) return []
+    return readdirSync(runs_dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map(({ name }) => name)
+        .filter((run_id) => {
+            const read = readRun({ runs_dir, run_id })
+            return (
+                read.ok &&
+                !STOP_ACTIONS.has(decide({ records: read.records }).type)
+            )
+        })
+        .toSorted()
+}
+
+/**
+ * One unfinished run, as `luca-run --unfinished` prints it for the board
+ * plugin (#375): whether Paseo may restart it with `--resume`, and why.
+ *
+ * - `resumable`: the engine was cut off (a crash, a kill); `restart` is true.
+ * - `launcher_stopped`: its last record is a launcher stop (the wrong login,
+ *   plan, or model). A restart would stop the same way, so `restart` is
+ *   false; `message` is the stop's reason.
+ * - `billing_stopped`: it stopped for billing, which sticks; `restart` is
+ *   false and `message` is the stop's reason.
+ */
+export const RestartableRunSchema = z.object({
+    run_id: z.string(),
+    restart: z.boolean(),
+    reason: z.enum(['resumable', 'launcher_stopped', 'billing_stopped']),
+    message: z.string().nullable(),
+})
+
+export type RestartableRun = z.infer<typeof RestartableRunSchema>
+
+/** What `luca-run --unfinished` prints: one JSON object, snake_case keys. */
+export const UnfinishedOutputSchema = z.object({
+    runs: z.array(RestartableRunSchema),
+})
+
+/** Whether Paseo may restart one unfinished run, from its records. */
+const restartOf = ({
+    run_id,
+    records,
+}: {
+    run_id: string
+    records: JournalRecord[]
+}): RestartableRun => {
+    // A billing stop sticks, wherever it is in the journal.
+    const billing = records.find(
+        (record) => record.kind === 'run_stopped' && record.content.billing
+    )
+    if (billing?.kind === 'run_stopped') {
+        return {
+            run_id,
+            restart: false,
+            reason: 'billing_stopped',
+            message: billing.content.reason,
+        }
+    }
+    const last = records.at(-1)
+    if (last?.kind === 'run_stopped' && !last.content.crashed) {
+        return {
+            run_id,
+            restart: false,
+            reason: 'launcher_stopped',
+            message: last.content.reason,
+        }
+    }
+    return { run_id, restart: true, reason: 'resumable', message: null }
+}
+
+/**
+ * The unfinished runs in `runs_dir` (`unfinishedRuns`), each with whether
+ * Paseo may restart it with `--resume` (#375). A run whose last record is a
+ * launcher stop is not restarted, since it would stop the same way; a run
+ * with a billing stop anywhere in its journal never is. Everything else was
+ * cut off and can go on from its journal.
+ *
+ * @example
+ * const runs = restartableRuns({ runs_dir: defaultRunsDir() })
+ * // [{ run_id: 'luca-20260923-141500-ab12', restart: true, reason: 'resumable', message: null }]
+ */
+export const restartableRuns = ({
+    runs_dir,
+}: {
+    runs_dir: string
+}): RestartableRun[] =>
+    unfinishedRuns({ runs_dir }).flatMap((run_id) => {
+        const read = readRun({ runs_dir, run_id })
+        return read.ok ? [restartOf({ run_id, records: read.records })] : []
+    })

package/engine/cli/upgrade-command.ts

@@ -1,6 +1,7 @@
 /**
  * `luca upgrade`: moves this computer to another published version of
- * Luca, never while a run is going:
+ * Luca, never while a run is going (its engine is running, or the board
+ * will restart it):
  *
  *   luca upgrade [--to <version>]
  *
@@ -10,24 +11,45 @@
  * board in Paseo, keeping its settings, and ends with `luca doctor`'s
  * computer checks. See `runUpgrade`.
  *
+ * Those last steps run in the version just installed (#529): upgrade
+ * hands off to it, as
+ *
+ *   luca upgrade --finish [--board-before <fingerprint>]
+ *
+ * which only Luca runs. It doesn't check for going runs or install
+ * anything: it reloads the board, copies Luca's skills, and runs the
+ * checks, with its own code. See `finishUpgrade`.
+ *
  * Exits 0 when done, 1 when it refused or a step failed, 2 on bad flags.
  */
+import { realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 
 import { z } from 'zod'
 
+import type { Paseo } from './computer-adapters'
 import {
     claudeOf,
     computerOf,
     lucaInstall,
     muninnHealth,
     muninnOf,
+    packageOf,
     paseoOf,
 } from './computer-adapters-real'
 import { computerChecks } from './computer-checks'
 import { reason } from './doctor-checks'
 import { defaultRegistryPath } from './going-runs'
-import { runUpgrade, type BunGlobal, type NpmRegistry } from './upgrade'
+import { listProcesses } from './live-runs'
+import {
+    runUpgrade,
+    type BunGlobal,
+    type HandOff,
+    type NewInstall,
+    type NpmRegistry,
+} from './upgrade'
+import { finishUpgrade } from './upgrade-finish'
 
 import { LUCA_PACKAGE } from '../config/luca-version'
 import { defaultRunsDir } from '../journal/journal'
@@ -75,60 +97,220 @@ const bunOf = ({ home }: { home: string }): BunGlobal => ({
     },
 })
 
-/** The `--to` version, `null` without it, or `undefined` on bad flags. */
-const parseTo = (argv: string[]): string | null | undefined => {
-    if (argv.length === 0) return null
-    const [flag, version] = argv
-    return flag === '--to' &&
-        argv.length === 2 &&
-        version !== undefined &&
-        version !== '' &&
-        !version.startsWith('-')
-        ? version
-        : undefined
+/**
+ * The new install's file older Luca looks for (see `upgrade-finish.ts`):
+ * next to its `luca.ts` when it can run `luca upgrade --finish`.
+ */
+const FINISH_MODULE = 'upgrade-finish.ts'
+
+/**
+ * The new install's `luca` entry, when it is `version` of Luca and can
+ * finish an upgrade; otherwise why not, in one sentence without a period.
+ * Finds it the way the PATH does: the `luca` in Bun's global commands
+ * folder (`bun pm bin -g`), which `bun add -g` points at the new install.
+ * Read-only.
+ *
+ * @example
+ * await findNewInstall({ bin_dir: '/Users/me/.bun/bin', version: '14.0.0-alpha.11' })
+ * // { ok: true, entry: '/Users/me/.bun/install/global/node_modules/@alecsibilia/luca/engine/cli/luca.ts' }
+ */
+export const findNewInstall = async ({
+    bin_dir,
+    version,
+}: {
+    bin_dir: string
+    version: string
+}): Promise<{ ok: true; entry: string } | { ok: false; why: string }> => {
+    const entry = await realpath(join(bin_dir, 'luca')).catch(() => null)
+    if (entry === null) {
+        return {
+            ok: false,
+            why: `Bun's global commands folder ${bin_dir} has no luca`,
+        }
+    }
+    const found = await packageOf(entry)
+    if (found?.name !== LUCA_PACKAGE || found.version !== version) {
+        const what =
+            found === null ? entry : `${found.name}@${found.version ?? '?'}`
+        return {
+            ok: false,
+            why: `The luca in ${bin_dir} is ${what}, not ${LUCA_PACKAGE}@${version}`,
+        }
+    }
+    if (!(await Bun.file(join(dirname(entry), FINISH_MODULE)).exists())) {
+        return {
+            ok: false,
+            why: `Luca ${version} can't finish an upgrade itself`,
+        }
+    }
+    return { ok: true, entry }
+}
+
+/**
+ * Runs `luca upgrade --finish` from `entry` with `bun_path`, its output
+ * going straight to this terminal; resolves to its exit code. Throws when
+ * it can't be started.
+ */
+export const handOff = async ({
+    bun_path,
+    entry,
+    board_before,
+    cwd,
+}: {
+    bun_path: string
+    entry: string
+    board_before: string | null
+    cwd: string
+}): Promise<HandOff> => {
+    const child = Bun.spawn({
+        cmd: [
+            bun_path,
+            entry,
+            'upgrade',
+            '--finish',
+            ...(board_before === null ? [] : ['--board-before', board_before]),
+        ],
+        cwd,
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    return { handed_off: true, exit_code: await child.exited }
+}
+
+/**
+ * The install `bun add -g` just made: found with `findNewInstall`, and
+ * handed the last steps with `handOff`. When it isn't found, or can't
+ * finish, says why, and this process runs them.
+ */
+const newInstallOf = ({ home }: { home: string }): NewInstall => ({
+    finish: async ({ version, board_before }) => {
+        const bin = await runCommand({
+            cmd: [process.execPath, 'pm', 'bin', '-g'],
+            cwd: home,
+            timeout_ms: 30_000,
+        })
+        if (bin.exit_code !== 0) {
+            return {
+                handed_off: false,
+                why: `Bun didn't say where its global commands are (bun pm bin -g exited ${bin.exit_code})`,
+            }
+        }
+        const found = await findNewInstall({
+            bin_dir: bin.stdout.trim(),
+            version,
+        })
+        if (!found.ok) return { handed_off: false, why: found.why }
+        return handOff({
+            bun_path: process.execPath,
+            entry: found.entry,
+            board_before,
+            cwd: home,
+        })
+    },
+})
+
+/** What `luca upgrade`'s flags ask for. */
+export type UpgradeArgs =
+    /** `luca upgrade [--to <version>]`; `to` is `null` without `--to`. */
+    | { finish: false; to: string | null }
+    /** `luca upgrade --finish [--board-before <fingerprint>]`, from an older Luca. */
+    | { finish: true; board_before: string | null }
+
+/** A flag's value: not empty and not another flag. */
+const isValue = (value: string | undefined): value is string =>
+    value !== undefined && value !== '' && !value.startsWith('-')
+
+/**
+ * The flags after `upgrade`, or `undefined` when they're bad. Pure.
+ *
+ * @example
+ * parseUpgradeArgs({ argv: ['--to', '14.0.0-alpha.3'] }) // { finish: false, to: '14.0.0-alpha.3' }
+ * parseUpgradeArgs({ argv: ['--finish'] }) // { finish: true, board_before: null }
+ */
+export const parseUpgradeArgs = ({
+    argv,
+}: {
+    argv: string[]
+}): UpgradeArgs | undefined => {
+    const [flag, value, ...rest] = argv
+    if (flag === undefined) return { finish: false, to: null }
+    if (flag === '--to' && isValue(value) && rest.length === 0) {
+        return { finish: false, to: value }
+    }
+    if (flag === '--finish' && value === undefined) {
+        return { finish: true, board_before: null }
+    }
+    if (flag === '--finish' && value === '--board-before') {
+        const [board_before, ...extra] = rest
+        if (isValue(board_before) && extra.length === 0) {
+            return { finish: true, board_before }
+        }
+    }
+    return undefined
 }
 
+/** Doctor's computer checks of the Luca on disk now. */
+const computerChecksOf =
+    ({ home, paseo }: { home: string; paseo: Paseo }) =>
+    async () =>
+        computerChecks({
+            home,
+            // Read again: an install changes the version on disk.
+            ...(await lucaInstall()),
+            computer: computerOf({ home }),
+            muninn: muninnOf({ home }),
+            muninn_health: muninnHealth,
+            claude: claudeOf({ home }),
+            paseo,
+            env: process.env,
+        })
+
 /** Runs `luca upgrade` with the flags after `upgrade`; returns the exit code. */
 export const upgradeCommand = async ({
     argv,
 }: {
     argv: string[]
 }): Promise<number> => {
-    const to = parseTo(argv)
-    if (to === undefined) {
+    const args = parseUpgradeArgs({ argv })
+    if (args === undefined) {
         console.error(UPGRADE_USAGE)
         return 2
     }
     const home = homedir()
     const paseo = paseoOf({ client_id: 'luca-upgrade' })
+    const log = (line: string) => {
+        console.log(line)
+    }
     try {
         const { luca_version, ...install } = await lucaInstall()
+        if (args.finish) {
+            const end = await finishUpgrade({
+                version: luca_version,
+                board_before: args.board_before,
+                home,
+                paseo,
+                ...install,
+                computer_checks: computerChecksOf({ home, paseo }),
+                log,
+            })
+            return end.ok ? 0 : 1
+        }
         const end = await runUpgrade({
-            to,
+            to: args.to,
+            home,
             installed_version: luca_version,
             runs_dir: defaultRunsDir(),
             registry_path: defaultRegistryPath({
                 env: process.env,
                 home_dir: home,
             }),
+            list_processes: listProcesses,
             npm: npmOf(),
             bun: bunOf({ home }),
             paseo,
             ...install,
-            computer_checks: async () =>
-                computerChecks({
-                    home,
-                    // Read again: the install changed the version on disk.
-                    ...(await lucaInstall()),
-                    computer: computerOf({ home }),
-                    muninn: muninnOf({ home }),
-                    muninn_health: muninnHealth,
-                    claude: claudeOf({ home }),
-                    paseo,
-                }),
-            log: (line) => {
-                console.log(line)
-            },
+            new_install: newInstallOf({ home }),
+            computer_checks: computerChecksOf({ home, paseo }),
+            log,
         })
         return end.ok ? 0 : 1
     } catch (error) {

package/engine/cli/upgrade-finish.ts

@@ -0,0 +1,149 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { setUpBoard } from './board-in-paseo'
+import type { PaseoPlugins } from './computer-adapters'
+import {
+    formatChecks,
+    hasProblem,
+    reason,
+    type DoctorCheck,
+} from './doctor-checks'
+import { installLucaSkills } from './luca-skills'
+
+/**
+ * The last steps of `luca upgrade`, after `bun add -g` (#529): reload the
+ * board, say when `/reload-skills` is needed, copy Luca's own skills, and
+ * run doctor's computer checks.
+ *
+ * They run in the newly installed Luca, not the one that installed it:
+ * `luca upgrade` hands off to the new install's `luca upgrade --finish`,
+ * so the board setup, the skills, and the checks are the new version's.
+ *
+ * Older Luca looks for this file next to the new install's `luca.ts` to
+ * tell whether the new install can finish an upgrade. Don't rename or move
+ * it.
+ */
+
+/** How upgrade ended; `message` is the last line it printed. */
+export type UpgradeEnd = { ok: boolean; message: string }
+
+/**
+ * A fingerprint of every file in `dir` but its `node_modules`, or `null`
+ * when it can't be read. Short, so it fits on a command line.
+ */
+export const boardFingerprint = async (dir: string): Promise<string | null> => {
+    const lines: string[] = []
+    const walk = async (at: string): Promise<void> => {
+        const entries = await readdir(at, { withFileTypes: true })
+        for (const entry of entries) {
+            const path = join(at, entry.name)
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules') await walk(path)
+            } else if (entry.isFile()) {
+                const bytes = await Bun.file(path).arrayBuffer()
+                lines.push(`${path}\t${Bun.hash(bytes)}`)
+            }
+        }
+    }
+    try {
+        await walk(dir)
+    } catch {
+        return null
+    }
+    return Bun.hash(lines.sort().join('\n')).toString(36)
+}
+
+/**
+ * Runs `luca upgrade`'s last steps for the installed `version`: reloads
+ * the board with its settings kept and its paths rewritten, says to run
+ * `/reload-skills` when the board's files differ from `board_before`,
+ * copies Luca's skills, then prints `computer_checks`. Ends with "Luca
+ * <version> is installed." Never throws.
+ *
+ * @example
+ * const end = await finishUpgrade({ version: '14.0.0-alpha.11', board_before, home, paseo, board_dir, skills_dir, engine_path, bun_path, computer_checks, log: console.log })
+ */
+export const finishUpgrade = async ({
+    version,
+    board_before,
+    home,
+    paseo,
+    board_dir,
+    skills_dir,
+    engine_path,
+    bun_path,
+    computer_checks,
+    log,
+}: {
+    /** The version just installed. */
+    version: string
+    /** The board folder's fingerprint before the install, or `null` when unknown. */
+    board_before: string | null
+    /** The home folder, whose `.claude/skills` gets Luca's own skills. */
+    home: string
+    paseo: PaseoPlugins
+    /** The board folder inside Luca's install folder. */
+    board_dir: string
+    /** The skills folder inside Luca's install folder. */
+    skills_dir: string
+    /** The real path of the installed `luca-run`. */
+    engine_path: string
+    /** Bun's own path. */
+    bun_path: string
+    /** Doctor's computer checks of the new install; none when not given. */
+    computer_checks?: () => Promise<DoctorCheck[]>
+    log: (line: string) => void
+}): Promise<UpgradeEnd> => {
+    const say = ({ message, ok }: UpgradeEnd): UpgradeEnd => {
+        log(`[luca upgrade] ${message}`)
+        return { ok, message }
+    }
+    try {
+        const board = await setUpBoard({
+            command: 'luca upgrade',
+            paseo,
+            // Upgrade only reloads; `luca init` asks to turn plugins on.
+            ask: async () => false,
+            board_dir,
+            engine_path,
+            bun_path,
+            log,
+        })
+        if (board.ok) {
+            const after = await boardFingerprint(board_dir)
+            if (
+                board_before === null ||
+                after === null ||
+                board_before !== after
+            ) {
+                log(
+                    "[luca upgrade] The board's files changed: run /reload-skills in a Paseo chat so its slash commands are up to date."
+                )
+            }
+        }
+        const skills = await installLucaSkills({
+            home,
+            skills_dir,
+            prefix: '[luca upgrade]',
+            log,
+        })
+        const end = say({
+            message: !board.ok
+                ? `Luca ${version} is installed, but the board wasn't reloaded. Run luca init to fix it.`
+                : !skills.ok
+                  ? `Luca ${version} is installed, but its skills weren't copied. Run luca doctor --fix to fix it.`
+                  : `Luca ${version} is installed.`,
+            ok: board.ok && skills.ok,
+        })
+        const checks = (await computer_checks?.()) ?? []
+        for (const line of formatChecks({ checks })) log(line)
+        return { ...end, ok: end.ok && !hasProblem({ checks }) }
+    } catch (error) {
+        // Such as computer checks that threw.
+        return say({
+            message: `Luca ${version} is installed, but its last steps failed: ${reason(error)}`,
+            ok: false,
+        })
+    }
+}