saeeol 1.2.9 → 1.3.1

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsgo --noEmit

package/AGENTS.md

@@ -0,0 +1,72 @@
+# SAEEOL agent guidelines
+
+## Build/Test
+
+- **Run**: `bun run --conditions=browser ./src/index.ts`
+- **Test**: `bun test` (all tests) or `bun test test/tool/tool.test.ts` (single test)
+- **Typecheck**: `bun run typecheck` (runs `tsgo --noEmit`)
+
+## Import Aliases
+
+- `@/*` maps to `./src/*`
+- `@tui/*` maps to `./src/cli/cmd/tui/*`
+
+## Key Patterns
+
+**Namespace modules** -- Code is organized as TypeScript namespaces, not classes. Each module exports a namespace with its Zod schemas, types, and functions:
+
+```ts
+export namespace Session {
+  export const Info = z.object({ ... })
+  export type Info = z.infer<typeof Info>
+  export const create = fn(z.object({ ... }), async (input) => { ... })
+}
+```
+
+**`Instance.state(init, dispose?)`** -- Per-project lazy singleton. Many modules register state this way. The state is tied to the project directory via `AsyncLocalStorage`:
+
+```ts
+const state = Instance.state(async () => {
+  // initialized once per project, cached
+  return { ... }
+})
+// later: (await state()).someValue
+```
+
+**`fn(schema, callback)`** -- Wraps functions with Zod input validation. Used for most exported functions:
+
+```ts
+export const get = fn(z.object({ id: z.string() }), async (input) => { ... })
+```
+
+**`Tool.define(id, init)`** -- All tools follow this pattern. The `init` returns `{ description, parameters, execute }`. Output is auto-truncated.
+
+**`BusEvent.define(type, schema)` + `Bus.publish()`** -- In-process pub/sub event system for cross-module communication.
+
+**`NamedError.create(name, schema)`** -- Structured errors with Zod schemas. Prefer these over throwing raw errors.
+
+**`iife()`** -- Immediately-invoked function expression helper. Used to avoid `let` statements per style guide.
+
+**Logging** -- Use `Log.create({ service: "name" })` pattern.
+
+## Process Spawning (Windows)
+
+On Windows, any `spawn`/`execFile` call without `windowsHide: true` will flash a cmd.exe console window at the user. Use `Process.spawn` from `src/util/process.ts` — it enforces `windowsHide: true` automatically. For `Bun.spawn`/`Bun.spawnSync`, pass `windowsHide` via the options object if the subprocess could create a visible console.
+
+The MCP `StdioClientTransport` (third-party SDK) is handled separately via a process shim in `src/mcp/index.ts` that sets `process.type = "browser"` when running inside the VS Code extension, which causes the SDK's internal `isElectron()` check to return `true` and enable `windowsHide`.
+
+## Storage
+
+Filesystem-based JSON, not a database. Data lives in `~/.local/share/saeeol/storage/`. Keys are path arrays: `Storage.write(["session", projectID, sessionID], data)`.
+
+## TUI
+
+Built with **SolidJS + OpenTUI** (`@opentui/solid`) -- a terminal UI framework. JSX renders to the terminal using elements like `<box>`, `<text>`, `<scrollbox>`. The TUI communicates with the server via `@saeeol/sdk`.
+
+## Server
+
+Hono-based HTTP server with OpenAPI spec generation. SSE for real-time events. When you add/change routes, regenerate the SDK (see root AGENTS.md for the command).
+
+## Providers and Models
+
+Uses the **Vercel AI SDK** as the abstraction layer. Providers are loaded from a bundled map or dynamically installed at runtime. Models come from models.dev (external API), cached locally.

package/BUN_SHELL_MIGRATION_PLAN.md

@@ -0,0 +1,136 @@
+# Bun shell migration plan
+
+Practical phased replacement of Bun `$` calls.
+
+## Goal
+
+Replace runtime Bun shell template-tag usage in `packages/saeeol/src` with a unified `Process` API in `util/process.ts`.
+
+Keep behavior stable while improving safety, testability, and observability.
+
+Current baseline from audit:
+
+- 143 runtime command invocations across 17 files
+- 84 are git commands
+- Largest hotspots:
+  - `src/cli/cmd/github.ts` (33)
+  - `src/worktree/index.ts` (22)
+  - `src/lsp/server.ts` (21)
+  - `src/installation/index.ts` (20)
+  - `src/snapshot/index.ts` (18)
+
+## Decisions
+
+- Extend `src/util/process.ts` (do not create a separate exec module).
+- Proceed with phased migration for both git and non-git paths.
+- Keep plugin `$` compatibility in 1.x and remove in 2.0.
+
+## Non-goals
+
+- Do not remove plugin `$` compatibility in this effort.
+- Do not redesign command semantics beyond what is needed to preserve behavior.
+
+## Constraints
+
+- Keep migration phased, not big-bang.
+- Minimize behavioral drift.
+- Keep these explicit shell-only exceptions:
+  - `src/session/prompt.ts` raw command execution
+  - worktree start scripts in `src/worktree/index.ts`
+
+## Process API proposal (`src/util/process.ts`)
+
+Add higher-level wrappers on top of current spawn support.
+
+Core methods:
+
+- `Process.run(cmd, opts)`
+- `Process.text(cmd, opts)`
+- `Process.lines(cmd, opts)`
+- `Process.status(cmd, opts)`
+- `Process.shell(command, opts)` for intentional shell execution
+
+Git helpers:
+
+- `Process.git(args, opts)`
+- `Process.gitText(args, opts)`
+
+Shared options:
+
+- `cwd`, `env`, `stdin`, `stdout`, `stderr`, `abort`, `timeout`, `kill`
+- `allowFailure` / non-throw mode
+- optional redaction + trace metadata
+
+Standard result shape:
+
+- `code`, `stdout`, `stderr`, `duration_ms`, `cmd`
+- helpers like `text()` and `arrayBuffer()` where useful
+
+## Phased rollout
+
+### Phase 0: Foundation
+
+- Implement Process wrappers in `src/util/process.ts`.
+- Refactor `src/util/git.ts` to use Process only.
+- Add tests for exit handling, timeout, abort, and output capture.
+
+### Phase 1: High-impact hotspots
+
+Migrate these first:
+
+- `src/cli/cmd/github.ts`
+- `src/worktree/index.ts`
+- `src/lsp/server.ts`
+- `src/installation/index.ts`
+- `src/snapshot/index.ts`
+
+Within each file, migrate git paths first where applicable.
+
+### Phase 2: Remaining git-heavy files
+
+Migrate git-centric call sites to `Process.git*` helpers:
+
+- `src/file/index.ts`
+- `src/project/vcs.ts`
+- `src/file/watcher.ts`
+- `src/storage/storage.ts`
+- `src/cli/cmd/pr.ts`
+
+### Phase 3: Remaining non-git files
+
+Migrate residual non-git usages:
+
+- `src/cli/cmd/tui/util/clipboard.ts`
+- `src/util/archive.ts`
+- `src/file/ripgrep.ts`
+- `src/tool/bash.ts`
+- `src/cli/cmd/uninstall.ts`
+
+### Phase 4: Stabilize
+
+- Remove dead wrappers and one-off patterns.
+- Keep plugin `$` compatibility isolated and documented as temporary.
+- Create linked 2.0 task for plugin `$` removal.
+
+## Validation strategy
+
+- Unit tests for new `Process` methods and options.
+- Integration tests on hotspot modules.
+- Smoke tests for install, snapshot, worktree, and GitHub flows.
+- Regression checks for output parsing behavior.
+
+## Risk mitigation
+
+- File-by-file PRs with small diffs.
+- Preserve behavior first, simplify second.
+- Keep shell-only exceptions explicit and documented.
+- Add consistent error shaping and logging at Process layer.
+
+## Definition of done
+
+- Runtime Bun `$` usage in `packages/saeeol/src` is removed except:
+  - approved shell-only exceptions
+  - temporary plugin compatibility path (1.x)
+- Git paths use `Process.git*` consistently.
+- CI and targeted smoke tests pass.
+- 2.0 issue exists for plugin `$` removal.

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM alpine AS base
+
+# Disable the runtime transpiler cache by default inside Docker containers.
+# On ephemeral containers, the cache is not useful
+ARG BUN_RUNTIME_TRANSPILER_CACHE_PATH=0
+ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=${BUN_RUNTIME_TRANSPILER_CACHE_PATH}
+RUN apk add libgcc libstdc++ ripgrep
+
+FROM base AS build-amd64
+COPY dist/saeeol-linux-x64-baseline-musl/bin/saeeol /usr/local/bin/saeeol
+
+FROM base AS build-arm64
+COPY dist/saeeol-linux-arm64-musl/bin/saeeol /usr/local/bin/saeeol
+
+ARG TARGETARCH
+FROM build-${TARGETARCH}
+RUN saeeol --version
+ENTRYPOINT ["saeeol"]

package/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit"
+
+export default defineConfig({
+  dialect: "sqlite",
+  schema: "./src/**/*.sql.ts",
+  out: "./migration",
+  dbCredentials: {
+    url: "/home/thdxr/.local/share/saeeol/saeeol.db",
+  },
+})

package/migration/20260127222353_familiar_lady_ursula/migration.sql

@@ -0,0 +1,90 @@
+CREATE TABLE `project` (
+	`id` text PRIMARY KEY,
+	`worktree` text NOT NULL,
+	`vcs` text,
+	`name` text,
+	`icon_url` text,
+	`icon_color` text,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	`time_initialized` integer,
+	`sandboxes` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `message` (
+	`id` text PRIMARY KEY,
+	`session_id` text NOT NULL,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	`data` text NOT NULL,
+	CONSTRAINT `fk_message_session_id_session_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE TABLE `part` (
+	`id` text PRIMARY KEY,
+	`message_id` text NOT NULL,
+	`session_id` text NOT NULL,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	`data` text NOT NULL,
+	CONSTRAINT `fk_part_message_id_message_id_fk` FOREIGN KEY (`message_id`) REFERENCES `message`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE TABLE `permission` (
+	`project_id` text PRIMARY KEY,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	`data` text NOT NULL,
+	CONSTRAINT `fk_permission_project_id_project_id_fk` FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE TABLE `session` (
+	`id` text PRIMARY KEY,
+	`project_id` text NOT NULL,
+	`parent_id` text,
+	`slug` text NOT NULL,
+	`directory` text NOT NULL,
+	`title` text NOT NULL,
+	`version` text NOT NULL,
+	`share_url` text,
+	`summary_additions` integer,
+	`summary_deletions` integer,
+	`summary_files` integer,
+	`summary_diffs` text,
+	`revert` text,
+	`permission` text,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	`time_compacting` integer,
+	`time_archived` integer,
+	CONSTRAINT `fk_session_project_id_project_id_fk` FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE TABLE `todo` (
+	`session_id` text NOT NULL,
+	`content` text NOT NULL,
+	`status` text NOT NULL,
+	`priority` text NOT NULL,
+	`position` integer NOT NULL,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	CONSTRAINT `todo_pk` PRIMARY KEY(`session_id`, `position`),
+	CONSTRAINT `fk_todo_session_id_session_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE TABLE `session_share` (
+	`session_id` text PRIMARY KEY,
+	`id` text NOT NULL,
+	`secret` text NOT NULL,
+	`url` text NOT NULL,
+	`time_created` integer NOT NULL,
+	`time_updated` integer NOT NULL,
+	CONSTRAINT `fk_session_share_session_id_session_id_fk` FOREIGN KEY (`session_id`) REFERENCES `session`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE INDEX `message_session_idx` ON `message` (`session_id`);--> statement-breakpoint
+CREATE INDEX `part_message_idx` ON `part` (`message_id`);--> statement-breakpoint
+CREATE INDEX `part_session_idx` ON `part` (`session_id`);--> statement-breakpoint
+CREATE INDEX `session_project_idx` ON `session` (`project_id`);--> statement-breakpoint
+CREATE INDEX `session_parent_idx` ON `session` (`parent_id`);--> statement-breakpoint
+CREATE INDEX `todo_session_idx` ON `todo` (`session_id`);