gemiterm 2.0.0

package/.opencode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

package/.opencode/skills/openspec-sync-specs/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

package/.serena/project.yml

@@ -0,0 +1,133 @@
+# the name by which the project can be referenced within Serena
+project_name: "gemiterm-bun-rewrite"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  angular             ansible             bash                clojure
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
+#   dart                elixir              elm                 erlang              fortran
+#   fsharp              go                  groovy              haskell             haxe
+#   hlsl                html                java                json                julia
+#   kotlin              lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        powershell          python
+#   python_jedi         python_ty           r                   rego                ruby
+#   ruby_solargraph     rust                scala               scss                solidity
+#   svelte              swift               systemverilog       terraform           toml
+#   typescript          typescript_vts      vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

package/AGENTS.md

@@ -0,0 +1,136 @@
+# GemiTerm Agent Guide (Bun Rewrite)
+
+Context for AI assistants and human contributors working in this repository.
+This file is the **persistent project context**; the per-session **goal** is supplied
+in the user message and is intentionally not duplicated here.
+
+---
+
+## What this project is
+
+A Bun-native TypeScript rewrite of **gemiterm**, a CLI for Google's Gemini web app.
+This rewrite will be released as **v2.0.0** and will replace the Python v1.4.1
+implementation currently published from `Expert-Vision-Software/gemiterm`.
+
+- **Upstream repo (reference only):** https://github.com/Expert-Vision-Software/gemiterm
+- **Local clone of upstream (Python v1.4.1 source, reference only):**
+  `C:\dev\projects\github\webgemini-cli\`
+- **This repo (Bun rewrite, the v2.0.0 target):** `C:\dev\projects\github\gemiterm-bun-rewrite\`
+- **Active branch:** `gemiterm-bun-rewrite`
+- **Status:** functionally complete (432/432 tests pass, 11 CLI commands
+  registered, auth flow working). CI/release pipeline is captured in the
+  `cross-platform-build-and-ci` OpenSpec change and is **not yet implemented in code** —
+  only the OpenSpec artifact is on disk (`openspec/changes/cross-platform-build-and-ci/`).
+
+## Goal & design intent
+
+The goal of **each work session** is supplied in the user message — read it there.
+
+Standing design intent (does not change session to session):
+
+- **Functional parity with the Python v1.4.1 implementation** is the baseline.
+- **Explicit deviation:** browser launch and automation go through the
+  `playwright-cli` subprocess (`@playwright/cli` on npm), not the
+  Python `playwright` SDK. This means some of the cross-platform browser
+  detection the Python code carried is no longer ours to do — `playwright-cli`
+  handles its own browser install (`playwright-cli install chromium`),
+  its own browser selection (`--browser=chromium|chrome|msedge|firefox|webkit`),
+  and its own CDP attach (`--cdp=`).
+- **Seamless v1.4.1 → v2.0.0 upgrade** is required: the v2.0.0 binary must
+  read the existing `%APPDATA%\gemiterm\` (Windows) / `~/gemiterm/`
+  (POSIX) config dir unchanged, and the new `install.ps1`/`install.sh` must
+  replace the v1.4.1 installer in place. This is captured in the
+  `v2-install-migration` OpenSpec change.
+
+## Sensitive area — do not modify lightly
+
+We troubleshooted and fixed a specific issue with **subprocess spawning and
+capturing authentication cookies** through `playwright-cli`. The fix landed in
+commits `4bc4de8` and `0ec3682`. The following files are the working
+implementation and must be treated as a regression-test gate:
+
+- `src/services/playwright-cli-driver.ts` — subprocess runner, argv builder,
+  cookie-list output parser. Owns the `BunPlaywrightRunner` and
+  `PlaywrightRunner` interface.
+- `src/services/cookie-monitor.ts` — login-detection polling loop. Uses the
+  sign-out link probe (`e4d1fef`), not a textarea/URL check.
+- `src/services/auth-service.ts` — orchestrates `playwright-cli-driver` +
+  `cookie-monitor` for the `auth` command flow.
+- `src/services/cookie-storage-service.ts` — 7-day freshness window, composes
+  `CookieStorage` via DI.
+
+If any change touches these files, the full test suite must pass
+(`bun run test` — 432/432 baseline) and the affected service-level tests
+(`tests/services/playwright-cli-driver.test.ts`,
+`tests/services/cookie-monitor.test.ts`,
+`tests/services/auth-service.test.ts`,
+`tests/services/cookie-storage-service.test.ts`) must be inspected manually.
+
+## Tooling
+
+- **openspec CLI** — used per the `openspec-*` skills for proposing, applying,
+  syncing, and archiving OpenSpec changes. The change artifacts in
+  `openspec/changes/` are the source of truth for pending work; the
+  committed specs in `openspec/specs/` describe the current state.
+- **deepwiki** — for any GitHub link mentioned in context or any third-party
+  library reference (e.g. `@playwright/cli`, `bun build`).
+- **plannotator** — `submit_plan` is for **action plans** that the user will
+  execute. Not for plans that themselves produce further plans.
+- **serena** — preferred for code exploration and editing. Use serena
+  `find_symbol`, `find_file`, `search_for_pattern`, `read_file`, `replace_*`
+  before falling back to `grep`/`glob`/`read`/`edit`.
+- **bash** — PowerShell 7+ (`pwsh`) on Windows. Use the `workdir` parameter
+  instead of `cd`; do not change directories inside a command.
+
+## How to work
+
+- Default to **delegating to subagents**; behave as a master coordinator.
+  Batch work into **sequential** chains (when output feeds the next step)
+  and **parallel** batches (when investigations are independent).
+- **Run `bun run test` after any non-trivial change** and confirm it stays
+  at the 432/432 baseline.
+- **Commit frequently** with conventional-commit messages. **Never push.**
+- The OpenSpec proposal/design/tasks artifacts in
+  `openspec/changes/<change-name>/` are documentation, not implementation.
+  They describe what to build; the build is done by a follow-up
+  implementation pass that the OpenSpec change's `tasks.md` tracks.
+- Read `openspec/MAESTRO_MIGRATION.md` before proposing new work — it maps
+  the original Python → Bun migration tasks to current status and to the
+  specific OpenSpec change that handles any remaining work.
+
+## Code conventions
+
+- **Path and file operations are mandatory mediation.** No file in `src/`
+  outside `src/infrastructure/path-utils.ts`, `src/infrastructure/io.ts`,
+  and `src/services/install-browser-service.ts` may import from
+  `node:fs`, `node:path`, or `node:os`. The lint script
+  `scripts/lint-path-mediation.{sh,ps1}` (also exposed as
+  `bun run lint:mediation`) enforces this. If you need a new path or
+  file-system helper, add it to the right module first and consume it
+  from there — do not bypass the mediation.
+- **All new file-system operations go through `io.ts`.** Use
+  `writeTextFile` / `readTextFile` / `readJsonFile` / `writeJsonFile` /
+  `ensureDir` / `existsFile` / `removeDir` / `renameDir` /
+  `isDirectory` / `listSubdirectories` / `safeReadTextFile`. New
+  functions should be added only when at least 2 call sites need them.
+- **All new path operations go through `path-utils.ts`.** Use
+  `resolvePath`, `joinPath`, `dirnamePath`, `getConfigDir`,
+  `getProfilesDir`, `getProfilePath`, `getProfileDir`,
+  `getDefaultProfileMarkerPath`, `isWSL`, `getProjectRoot`, or
+  `getPackageJson`. Do not call `node:path` directly.
+- **Errors from `io.ts` throw `IOError`** with a `cause` field for the
+  original error. Do not catch and re-throw the raw `node:fs` error.
+
+## Repo hygiene
+
+These items are tracked in the `cross-platform-build-and-ci` change's tasks:
+
+- Orphan file literally named `{` at the repo root.
+- Stray bare `{` line in `.gitignore:23`.
+- Unused `commander@^15.0.0` in `package.json:29` (the CLI uses hand-rolled
+  argv parsing; `commander` is installed but never imported).
+- Empty `src/commands/` placeholder containing only `.gitkeep`.
+- `bun run build` is broken on Bun 1.3.x (`--compile` no longer accepts
+  `--outdir`).
+
+

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [2.0.0] - 2026-06-08
+
+Initial Bun typescript rewrite release. All 11 CLI commands, auth flow, and cross-platform delivery.