@alecsibilia/luca 13.0.1 → 14.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @alecsibilia/luca
+
+## 14.0.0-alpha.0
+
+### Major Changes
+
+- f732641: Luca v14: new Luca on npm

package/README.md

@@ -1,47 +1,119 @@
 # @alecsibilia/luca
 
-Luca — spec-driven agentic development workflow for [Claude Code](https://claude.com/claude-code).
+Luca turns a spec on GitHub Issues into a reviewed pull request. A run takes the spec's tickets through the engine, plain code that picks every next step, while Claude agents write the tests and the code and a fresh reviewer checks each ticket. The board shows the run live in Paseo.
 
-The `luca` CLI bootstraps [MuninnDB](https://github.com/asibilia/muninn) for long-term memory, installs the Luca skill/command/agent set into your global Claude home, and writes the per-project `.luca/` skeleton that drives the autonomous pipeline.
+This is Luca v14, in alpha. Old Luca (v13) is still on npm; see [Coming from v13](#coming-from-v13).
 
-## What's in the box
+## What you need
 
-This package is an umbrella: at build time it inlines three private workspace packages into a single self-contained tarball.
+- macOS
+- the Paseo desktop app, 0.9.1 or newer
+- Claude Code 2.1.280 or newer, signed in with a Claude **Pro or Max** plan (not the Free plan, and not an API key)
+- [Bun](https://bun.sh)
+- git
+- the GitHub CLI, `gh`, signed in (`gh auth login`)
+- GitHub Issues as your repo's tracker
 
-| Sub-package | Role |
-|---|---|
-| `@alecsibilia/luca-cli` | The `luca` command surface (init, doctor, state, phase, todo, telemetry, …) |
-| `@alecsibilia/luca-core` | Deterministic logic — state machine, `.luca/` contract, telemetry, complexity routing, verification, confidence journal |
-| `@alecsibilia/luca-tools` | Artifact definitions (agents, skills, commands, rules, hooks) + the compiler that emits them to the Claude Code shape |
+## First run
 
-You do not depend on those names. Just `@alecsibilia/luca`.
+1. Install Luca:
 
-## Installation
+   ```bash
+   bun add -g @alecsibilia/luca
+   ```
+
+   While v14 is in alpha, npm's `latest` is still v13, so install `@alecsibilia/luca@alpha` for now.
+
+2. Set up this computer, once:
+
+   ```bash
+   luca init
+   ```
+
+3. Set up your repo, once, from inside it:
+
+   ```bash
+   luca setup
+   ```
+
+4. In Claude Code, in your repo, run `/setup-matt-pocock-skills` so the planning skills know your repo.
+5. Write a spec with `/to-spec`, then split it into tickets with `/to-tickets`.
+6. In a Paseo chat, type `/luca-run <spec number>`. The board shows the run in the side panel, and the run ends in one pull request.
+
+## Commands
+
+| Command | What it does |
+| ------- | ------------ |
+| `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, and the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`). It asks before turning on Paseo's plugins, and leaves skills you already have alone. `--skip-skills` skips the skills. |
+| `luca setup` | Gets the repo in this folder ready: the labels a run needs (and the `release:*` labels when the repo uses changesets), `.luca/config.json`, and a check of GitHub sub-issues and dependencies. `--base <branch>` names the base branch. |
+| `luca doctor` | Checks this computer, this repo when you're in one, and what v13 left behind. Each problem comes with its exact fix. `luca doctor --fix` fixes what's safe without asking: it never deletes (v13 files go to a dated backup folder) and never commits, and it lists the repo files to commit. |
+| `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. Then it reloads the board and says when to run `/reload-skills`. |
+| `luca upgrade --to <version>` | Installs that exact version, an older one too, to go back when a version breaks. |
+
+`init`, `setup`, and `upgrade` end with their part of `luca doctor`'s checks.
+
+## Memory
+
+Luca's runs remember what they learn with MuninnDB. `luca init` installs and starts it, adds it to Claude Code as the user-scope `muninn` server, and adds a login item that starts it again after a reboot.
+
+If you run MuninnDB your own way, or want no memory, skip that step:
 
 ```bash
-bun add -g @alecsibilia/luca
-# or
-npm install -g @alecsibilia/luca
+luca init --skip-muninndb
 ```
 
-## Quickstart
+A run with no `muninn` server in Claude Code has memory off, and `luca doctor` warns "memory off" rather than failing.
+
+## Coming from v13
+
+v14 is a new Luca: `/lu`, `/luca-init`, v13's skills, agents, commands, hooks, and status line are gone. Matt Pocock's skills do the planning, and `/luca-run` does the building. Run `luca doctor --fix` to move what v13 left behind to a backup folder. See the [migration guide](https://github.com/asibilia/luca-framework/blob/main/docs/migrating-to-v14.md).
+
+To stay on v13, don't install v14: v13 stays on npm. One computer holds one global `luca`.
+
+## For maintainers
+
+### Releasing
+
+This package is released with changesets and the [`release.yml`](https://github.com/asibilia/luca-framework/blob/main/.github/workflows/release.yml) workflow. The repo is in changesets' pre mode `alpha`, so only `14.0.0-alpha.N` versions go out, under npm's `alpha` tag, and `latest` stays on `13.0.1`.
+
+1. Merge a PR with a changeset (`bunx changeset`). On the push to `main`, the workflow opens or updates the Version PR, "chore(release): version packages (...)". This package, `@luca/engine`, and `@luca/board` are one `fixed` group in `.changeset/config.json`: this package ships the engine's and board's files without depending on them, so a changeset that names only the private engine or board (as the engine's own changesets on its runs' PRs do) still bumps this package.
+2. The Version PR is opened by the bot, so its checks don't start on their own: on the PR, click **Approve workflows to run**.
+3. Merge the Version PR. The workflow sees no pending changesets and a version that isn't on npm yet, so it publishes: the PR checks, `bun pm pack`, an install of the tarball with `luca-run --demo`, a guard that fails unless the version is `-alpha.N`, `npm publish --tag alpha` over npm trusted publishing (no token), and a GitHub release marked as a prerelease.
+
+Switch on `latest` later, after a real `tmnb` run works, with one reviewed PR that runs `changeset pre exit` and changes the `-alpha.N` guard (and the `--tag alpha`) in `release.yml` together.
+
+### What's in the package
+
+This is the one package that goes to npm. It's TypeScript source with no build and no bundle, because the engine only runs on Bun. It has two commands: `luca`, for people, and `luca-run`, the engine, which the board starts. At pack time it copies in:
+
+| Folder | What it is |
+| ------ | ---------- |
+| `engine/` | The engine's source, from [`packages/engine/src`](../engine/src). Both bins point into it. |
+| `board/` | The board plugin's folder, from [`packages/board`](../board): `paseo-plugin.json`, its entry points, its client, server, and shared code, and its own `package.json`, so Paseo can install it as a folder source. |
+| `LICENSE` | The repo's license. |
+
+Test files and test helpers stay out. The engine and the board stay private workspace packages, and this package lists every package they import at runtime as its own dependency.
+
+### Pack it
+
+Pack it with Bun, from this folder:
 
 ```bash
-luca init          # Bootstrap MuninnDB + install Claude skills/commands/agents globally
-luca vault:init    # Configure the per-project MuninnDB vault
-luca doctor        # Environment diagnostics
+bun pm pack
 ```
 
-Then, inside Claude Code, run the `/lu` slash command to drive the autonomous pipeline.
+`bun pm pack` runs the `prepack` script ([`scripts/copy-sources.ts`](scripts/copy-sources.ts)), which copies the engine and the board in, then packs, then runs `postpack`, which removes the copies again.
 
-## CLI reference
+`bun pm pack` leaves out every `bunfig.toml` by default, even one named in `files`. The engine needs its own `cli/bunfig.toml`, because the board starts it with `--config` pointing there. So the script writes an `.npmignore` into `engine/` that puts it back.
 
-Use `luca --help` for the full surface, and `luca <command> --help` per noun group.
+It must be packed with Bun. The manifest uses the workspace's `catalog:` and `workspace:` versions, and `bun pm pack` turns them into real versions in the packed `package.json`. A plain `npm pack` ships them unchanged, and an install from that tarball fails. Publish the tarball Bun made:
 
-Lifecycle: `init`, `vault:init`, `doctor`, `retro`, `claim-verify`, `telemetry`, `rules`, `classify`, `hook`, `repair`, `version`.
+```bash
+npm publish <tarball> --tag alpha
+```
 
-Write surface (structured mutations of `.luca/`): `state`, `phase`, `roadmap`, `preferences`, `todo`, `pr-review`, `repo`, `checks`, `branch`, `workflow`, `confidence`, `verification`.
+npm does the publishing because Bun can't publish over npm's trusted publishing (OIDC) yet.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+Apache License 2.0. See [LICENSE](https://github.com/asibilia/luca-framework/blob/main/LICENSE).

package/board/client/board-look.ts

@@ -0,0 +1,292 @@
+import { useEffect, useState } from 'react'
+
+import type { PluginTheme } from '@getpaseo/plugin'
+import { Platform } from 'react-native'
+
+import type { Tone } from '../shared/board-rows'
+import type {
+    LensState,
+    RunStatus,
+    TicketStage,
+    UsageLevel,
+} from '../shared/board-state'
+
+/**
+ * Colors and words shared by the side panel and the chat rows, so both views
+ * match. Every color comes from the host theme.
+ */
+
+export const MONO = Platform.select({ ios: 'Menlo', default: 'monospace' })
+
+/** How often a running step's time counts up. */
+const TICK_MS = 1000
+
+/**
+ * The clock, ticking every second, so a running step's time counts up
+ * even when no new record redraws the view.
+ *
+ * @example
+ * const now = useNow()
+ * currentStepText({ step, now })
+ */
+export const useNow = (): number => {
+    const [now, setNow] = useState(() => Date.now())
+    useEffect(() => {
+        const timer = setInterval(() => setNow(Date.now()), TICK_MS)
+        return () => clearInterval(timer)
+    }, [])
+    return now
+}
+
+/** Opacity for dimmed parts: empty stages, the final review before it starts. */
+export const DIMMED = 0.45
+
+/**
+ * Plan usage color: green below 60%, yellow 60–85%, red above 85%, muted
+ * with no reading.
+ */
+export const usageColor = ({
+    level,
+    theme,
+}: {
+    level: UsageLevel | null
+    theme: PluginTheme
+}): string => {
+    if (level === null) return theme.colors.foregroundMuted
+    switch (level) {
+        case 'ok':
+            return theme.colors.statusSuccess
+        case 'warn':
+            return theme.colors.statusWarning
+        case 'high':
+            return theme.colors.statusDanger
+    }
+}
+
+export const stageColor = ({
+    stage,
+    theme,
+}: {
+    stage: TicketStage
+    theme: PluginTheme
+}): string => {
+    switch (stage) {
+        case 'building':
+        case 'reviewing':
+            return theme.colors.accent
+        case 'stuck':
+            return theme.colors.statusDanger
+        case 'done':
+            return theme.colors.statusSuccess
+        case 'blocked':
+        case 'skipped':
+            return theme.colors.foregroundMuted
+    }
+}
+
+export const lensColor = ({
+    state,
+    theme,
+}: {
+    state: LensState
+    theme: PluginTheme
+}): string => {
+    switch (state) {
+        case 'waiting':
+            return theme.colors.foregroundMuted
+        case 'reviewing':
+            return theme.colors.accent
+        case 'fixing':
+            return theme.colors.statusWarning
+        case 'clean':
+            return theme.colors.statusSuccess
+    }
+}
+
+export const toneColor = ({
+    tone,
+    theme,
+}: {
+    tone: Tone
+    theme: PluginTheme
+}): string => {
+    switch (tone) {
+        case 'info':
+            return theme.colors.accent
+        case 'success':
+            return theme.colors.statusSuccess
+        case 'warning':
+            return theme.colors.statusWarning
+        case 'danger':
+            return theme.colors.statusDanger
+    }
+}
+
+export const statusColor = ({
+    status,
+    theme,
+}: {
+    status: RunStatus
+    theme: PluginTheme
+}): string => {
+    switch (status) {
+        case 'done':
+            return theme.colors.statusSuccess
+        case 'stuck':
+        case 'stopped':
+        case 'refused':
+        case 'ended_with_error':
+            return theme.colors.statusDanger
+        case 'limit_wait':
+        case 'usage_line_wait':
+            return theme.colors.statusWarning
+        case 'starting':
+        case 'intake':
+        case 'building':
+        case 'final_review':
+            return theme.colors.accent
+        case 'nothing_to_do':
+            return theme.colors.foregroundMuted
+    }
+}
+
+/** A run status in words. */
+export const statusText = ({ status }: { status: RunStatus }): string => {
+    switch (status) {
+        case 'starting':
+            return 'starting'
+        case 'intake':
+            return 'intake'
+        case 'building':
+            return 'building'
+        case 'final_review':
+            return 'final review'
+        case 'limit_wait':
+            return 'limit wait'
+        case 'usage_line_wait':
+            return 'paused at the usage line'
+        case 'done':
+            return 'done'
+        case 'refused':
+            return 'refused'
+        case 'nothing_to_do':
+            return 'nothing to do'
+        case 'stuck':
+            return 'stuck'
+        case 'stopped':
+            return 'run stopped'
+        case 'ended_with_error':
+            return 'engine stopped'
+    }
+}
+
+/** A usage percent, or "–" for a window with no reading yet. */
+export const percentText = ({ percent }: { percent: number | null }): string =>
+    percent === null ? '–' : `${percent}%`
+
+/** 1234 → "1.2k"; 9000000 → "9.0M". */
+export const tokensText = ({ tokens }: { tokens: number }): string => {
+    if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+    return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens)
+}
+
+const two = ({ value }: { value: number }) => String(value).padStart(2, '0')
+
+/** An ISO time as local "hh:mm", or the text itself when it isn't a time. */
+export const clockText = ({ iso }: { iso: string }): string => {
+    const date = new Date(iso)
+    if (Number.isNaN(date.getTime())) return iso
+    return `${two({ value: date.getHours() })}:${two({ value: date.getMinutes() })}`
+}
+
+/** When a limit resets, e.g. "17:00 (in 1h 20m)". */
+export const resetsText = ({
+    resets_at,
+    now,
+}: {
+    resets_at: string | null
+    now: number
+}): string => {
+    if (!resets_at) return 'unknown'
+    const at = new Date(resets_at).getTime()
+    if (Number.isNaN(at)) return resets_at
+    const minutes = Math.max(0, Math.round((at - now) / 60_000))
+    const left =
+        minutes >= 60
+            ? `${Math.floor(minutes / 60)}h ${minutes % 60}m`
+            : `${minutes}m`
+    return `${clockText({ iso: resets_at })} (in ${left})`
+}
+
+/**
+ * A limit wait's headline, e.g. "Plan limit hit (five-hour window)". `window`
+ * is already in words; without one it's just "Plan limit hit".
+ */
+export const limitHitText = ({ window }: { window: string | null }): string =>
+    window === null ? 'Plan limit hit' : `Plan limit hit (${window} window)`
+
+/** "The run waits until 17:00 (in 1h 20m) and then carries on by itself." */
+export const limitUntilText = ({
+    resets_at,
+    now,
+}: {
+    resets_at: string | null
+    now: number
+}): string =>
+    `The run waits until ${resetsText({ resets_at, now })} and then carries on by itself.`
+
+/**
+ * What a limit wait means, e.g. "Plan limit hit (weekly window). The run
+ * waits until 17:00 (in 1h 20m) and then carries on by itself."
+ */
+export const limitWaitText = ({
+    window,
+    resets_at,
+    now,
+}: {
+    window: string | null
+    resets_at: string | null
+    now: number
+}): string =>
+    `${limitHitText({ window })}. ${limitUntilText({ resets_at, now })}`
+
+/**
+ * What a pause at the usage line means, e.g. "Paused at the weekly usage
+ * line: the account's weekly window is at 82% (line 80%). The run waits
+ * until 11:00 (in 3h 5m), or until the line is raised, and then carries on
+ * by itself."
+ */
+export const usageLineWaitText = ({
+    window,
+    line,
+    percent,
+    resets_at,
+    now,
+}: {
+    window: string
+    line: number
+    percent: number
+    resets_at: string
+    now: number
+}): string =>
+    `Paused at the ${window} usage line: the account's ${window} window is at ${percent}% (line ${line}%). ` +
+    `The run waits until ${resetsText({ resets_at, now })}, or until the line is raised, and then carries on by itself.`
+
+/** "Spec #10 · Add CSV export", or "Demo run" before the engine names one. */
+export const runTitle = ({
+    spec_number,
+    spec_title,
+    demo,
+}: {
+    spec_number: number | null
+    spec_title: string | null
+    demo: boolean
+}): string => {
+    const spec =
+        spec_number === null
+            ? demo
+                ? 'Demo run'
+                : 'Run'
+            : `${demo ? 'Demo · ' : ''}Spec #${spec_number}`
+    return spec_title ? `${spec} · ${spec_title}` : spec
+}