From 63478dd9b5be01ca9387b3a9a2cd0fb4339982f6 Mon Sep 17 00:00:00 2001 From: vadimvlasenko Date: Fri, 3 Jul 2026 16:58:59 +0300 Subject: [PATCH 1/4] docs(cli): document macOS dmg installer and script options in install README --- install/README.md | 73 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 65 insertions(+), 8 deletions(-) diff --git a/install/README.md b/install/README.md index 3b0daa3e..55af67e2 100644 --- a/install/README.md +++ b/install/README.md @@ -1,6 +1,11 @@ # CodeMie Bootstrap Installers -This directory contains source files for the lightweight CodeMie bootstrap installers. +This directory contains source files for the CodeMie installers: + +- **GUI installers** — a signed `.dmg` (macOS, Apple Silicon) and a `.exe` wizard (Windows) that install and configure CodeMie with no terminal required. +- **Script installers** — plain shell/PowerShell bootstrap scripts that install via npm. Prefer these for CI, headless machines, or when a GUI installer is unavailable. + +## Distribution Models Two distribution models are supported: @@ -9,12 +14,13 @@ Two distribution models are supported: - Windows CMD: `install/windows/install.cmd` - macOS/Linux/WSL: `install/macos/install.sh` -2. **Windows Installation Wizard** — a self-contained GUI installer: - - `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` +2. **GUI installers** — self-contained desktop applications: + - macOS: `install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` + - Windows: `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` -The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a Windows-built `.exe`. +The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a GUI installer. -Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. +Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. `CODEMIE_INSTALL_URL` points at the **directory** containing `install.ps1`, not the file itself. Channel selection is not implemented in the bootstrap scripts yet. Install the default npm package version, or pass an explicit version with PowerShell `-Version` or shell `CODEMIE_PACKAGE_VERSION`. @@ -48,11 +54,40 @@ https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/i https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh ``` -For reproducible installs, replace `main` with a release tag such as `v0.0.57`. +For reproducible installs, replace `main` with a release tag such as `v0.8.0`. + +## Script Options + +### Windows PowerShell (`install/windows/install.ps1`) + +| Parameter | Default | Values / Purpose | +|---|---|---| +| `-Mode` | `portable` | `portable` = npm prefix under `-InstallRoot` with shim `.cmd` files in `bin/` and a user PATH update; `npm-global` = plain `npm install -g` into the existing npm prefix | +| `-Version` | *(empty)* | Pin `@codemieai/code` to a specific version | +| `-RegistryUrl` | `https://registry.npmjs.org/` | npm registry used for resolution and install | +| `-ScopeRegistryUrl` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | +| `-InstallRoot` | `%LOCALAPPDATA%\CodeMie` | Portable install root (`-Mode portable` only) | +| `-DryRun` | *(switch)* | Print every action without executing it | + +### macOS / Linux / WSL (`install/macos/install.sh`) + +| Env var | Default | Values / Purpose | +|---|---|---| +| `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | +| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | +| `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | +| `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | +| `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | + +Pin a version on macOS/Linux/WSL: + +```bash +curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | env CODEMIE_PACKAGE_VERSION=0.8.0 bash +``` ## Windows Defaults -Windows installs into the current user's local profile by default: +Windows installs into the current user's local profile by default (`-Mode portable`): ```text %LOCALAPPDATA%\CodeMie @@ -64,7 +99,7 @@ Known limitation: `install/windows/install.cmd` forwards arguments to PowerShell ## macOS/Linux Defaults -macOS, Linux, and WSL prefer npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix. +macOS, Linux, and WSL use `CODEMIE_INSTALL_MODE=auto` by default: npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix (`$HOME/.codemie/npm-prefix`). ## Windows Installation Wizard @@ -118,6 +153,28 @@ All wizard output is written to: The log persists across runs. Each line is prefixed with an ISO-8601 timestamp and a tag: `[OUT]` stdout, `[ERR]` stderr, `[INF]` info, `[OK]` success, `[CMD]` command. +## macOS Installation Wizard + +`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` is a signed macOS desktop GUI application for **Apple Silicon (aarch64)** Macs. It installs and configures the CodeMie CLI and Claude engine end-to-end with no terminal required. (An Intel x86_64 build is not shipped.) + +The wizard is built from a separate repository (`codemie-claude-installer-mac`); the `.dmg` committed here is the distributed artifact. + +### Running the Wizard + +Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install folder](https://github.com/codemie-ai/codemie-code/tree/main/install/macos), open it, and run the app. The wizard walks the user through installing prerequisites (Xcode Command Line Tools, Node.js, Git), the CodeMie CLI, an interactive `codemie setup`, the Claude engine via `codemie install claude`, and a final `codemie doctor` validation. + +### Log File + +Wizard output is written to: + +```text +~/Library/Logs/CodeMie/ +``` + +The log persists across runs. + +> The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. + ## Release Artifacts Run this command to prepare publishable artifacts: From 457ff8940dd3f2fd72a7d861e2ca0a0dd888387c Mon Sep 17 00:00:00 2001 From: vadimvlasenko Date: Fri, 3 Jul 2026 17:06:46 +0300 Subject: [PATCH 2/4] docs(cli): fix INSTALL_MODE typo and soften macOS wizard log path --- install/README.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/install/README.md b/install/README.md index 55af67e2..cf9b698f 100644 --- a/install/README.md +++ b/install/README.md @@ -74,7 +74,7 @@ For reproducible installs, replace `main` with a release tag such as `v0.8.0`. | Env var | Default | Values / Purpose | |---|---|---| | `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | -| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | +| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `CODEMIE_INSTALL_MODE` resolves to `user-prefix` | | `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | | `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | | `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | @@ -165,13 +165,7 @@ Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install fold ### Log File -Wizard output is written to: - -```text -~/Library/Logs/CodeMie/ -``` - -The log persists across runs. +Wizard output is written to `~/Library/Logs/CodeMie/wizard.log` (per the macOS installer plan; the wizard source lives in a separate repository). The log persists across runs. > The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. From 80a703f40abca7a604967460b341a287af444014 Mon Sep 17 00:00:00 2001 From: vadimvlasenko Date: Fri, 3 Jul 2026 17:09:08 +0300 Subject: [PATCH 3/4] docs(skills): add update-install-readme planning artifacts --- .../actual-complexity.json | 17 ++ .../code-review-check.diff | 28 ++ .../code-review-check.json | 24 ++ .../code-review-final.json | 39 +++ .../code-review.diff | 116 ++++++++ .../gate-plan.json | 16 + .../2026-07-03-update-install-readme/plan.md | 273 ++++++++++++++++++ .../qa-report.md | 32 ++ .../technical-analysis.md | 75 +++++ 9 files changed, 620 insertions(+) create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md create mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json new file mode 100644 index 00000000..1d7d1b82 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json @@ -0,0 +1,17 @@ +{ + "mode": "actual", + "size": "XS", + "total": 6, + "dimensions": { + "files_changed": {"score": 1, "note": "1 file (install/README.md)"}, + "lines_changed": {"score": 1, "note": "59 insertions, 8 deletions"}, + "architecture_surface": {"score": 1, "note": "no code; documentation only"}, + "test_surface": {"score": 1, "note": "no tests; docs-only, no behavior to assert"}, + "risk": {"score": 1, "note": "no security/auth/migration/breaking surface; docs change"}, + "cross_layer": {"score": 1, "note": "single file, no layer crossings"} + }, + "diffstat": "1 file changed, 59 insertions(+), 8 deletions(-)", + "changed_files": ["install/README.md"], + "assessed_at": "2026-07-03T14:12:00Z", + "note": "Assessed inline: complexity-assessor subagent unavailable (codegraph MCP not connected). Score reflects direct inspection — 1 docs file, low-risk, no code/tests/layers." +} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff new file mode 100644 index 00000000..7b800959 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff @@ -0,0 +1,28 @@ +diff --git a/install/README.md b/install/README.md +index 55af67e..cf9b698 100644 +--- a/install/README.md ++++ b/install/README.md +@@ -74,7 +74,7 @@ For reproducible installs, replace `main` with a release tag such as `v0.8.0`. + | Env var | Default | Values / Purpose | + |---|---|---| + | `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | +-| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | ++| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `CODEMIE_INSTALL_MODE` resolves to `user-prefix` | + | `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | + | `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | + | `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | +@@ -165,13 +165,7 @@ Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install fold + + ### Log File + +-Wizard output is written to: +- +-```text +-~/Library/Logs/CodeMie/ +-``` +- +-The log persists across runs. ++Wizard output is written to `~/Library/Logs/CodeMie/wizard.log` (per the macOS installer plan; the wizard source lives in a separate repository). The log persists across runs. + + > The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. + diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json new file mode 100644 index 00000000..80ba322e --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json @@ -0,0 +1,24 @@ +{ + "decision": "approve", + "rationale": "Check round re-verified both blocking findings against the fix-up diff. CR-001 resolved: CODEMIE_NPM_PREFIX row now reads 'CODEMIE_INSTALL_MODE resolves to user-prefix' — matches the documented env var. CR-002 resolved: macOS log path softened to attribution framing with the plan doc's file path (~/Library/Logs/CodeMie/wizard.log), no longer stated as unverifiable certainty. Fix-up diff is 2+/8- on the same single file, introduces no new high-risk issue (docs-only, no security/API/runtime surface). business_review and standards_review carried forward unchanged from the final round.", + "confidence": "high", + "risk_flags": [], + "business_review": [ + {"criterion": "1. macOS .dmg in intro + distribution list + new wizard section", "status": "pass"}, + {"criterion": "2. Full PowerShell install.ps1 parameter table", "status": "pass"}, + {"criterion": "3. Full install.sh env-var table", "status": "pass"}, + {"criterion": "4. Refresh stale tag v0.0.57 -> v0.8.0", "status": "pass"}, + {"criterion": "5. Name Windows portable vs macOS auto modes", "status": "pass"}, + {"criterion": "6. Keep Windows wizard / Release Artifacts / Defaults verbatim", "status": "partial", "notes": "Wizard + Release Artifacts byte-identical; Defaults prose edited to satisfy criterion 5 — resolved by design"} + ], + "standards_review": [ + {"check": "commit-format", "status": "pass", "notes": "docs(cli): ... matches Conventional Commits; scope 'cli' in allowed enum"}, + {"check": "code-quality", "status": "na", "notes": "docs-only change, no code"}, + {"check": "security", "status": "na", "notes": "docs-only, no credentials/paths/injection surface"} + ], + "findings": [], + "finding_status": [ + {"id": "CR-001", "status": "resolved", "evidence": "fix-up diff line: '+| CODEMIE_NPM_PREFIX | $HOME/.codemie/npm-prefix | npm prefix used when CODEMIE_INSTALL_MODE resolves to user-prefix |'"}, + {"id": "CR-002", "status": "resolved", "evidence": "fix-up diff replaces the over-certain directory path with 'Wizard output is written to ~/Library/Logs/CodeMie/wizard.log (per the macOS installer plan; the wizard source lives in a separate repository).'"} + ] +} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json new file mode 100644 index 00000000..0345f00a --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json @@ -0,0 +1,39 @@ +{ + "decision": "request-changes", + "rationale": "All 3 lenses ran; 5/6 acceptance criteria pass. Two major patch findings: a typo referencing a non-existent INSTALL_MODE variable (CR-001) and an over-certain macOS log-path claim that is unverifiable from this repo and mismatches the plan doc's file path (CR-002). Both are small factual fixes. Acceptance criterion 6 (verbatim preservation) is partial because the Defaults prose was edited to satisfy criterion 5 (name the modes) — resolved by design; substantive wizard/artifacts content is byte-identical.", + "confidence": "medium", + "risk_flags": [], + "business_review": [ + {"criterion": "1. macOS .dmg in intro + distribution list + new wizard section", "status": "pass"}, + {"criterion": "2. Full PowerShell install.ps1 parameter table", "status": "pass"}, + {"criterion": "3. Full install.sh env-var table", "status": "pass"}, + {"criterion": "4. Refresh stale tag v0.0.57 -> v0.8.0", "status": "pass"}, + {"criterion": "5. Name Windows portable vs macOS auto modes", "status": "pass"}, + {"criterion": "6. Keep Windows wizard / Release Artifacts / Defaults verbatim", "status": "partial", "notes": "Wizard + Release Artifacts byte-identical; Defaults prose edited to satisfy criterion 5 — resolved by design"} + ], + "standards_review": [ + {"check": "commit-format", "status": "pass", "notes": "docs(cli): ... matches Conventional Commits; scope 'cli' is in allowed enum (install was not)"}, + {"check": "code-quality", "status": "na", "notes": "docs-only change, no code"}, + {"check": "security", "status": "na", "notes": "docs-only, no credentials/paths/injection surface"} + ], + "findings": [ + { + "id": "CR-001", + "triage": "patch", + "severity": "major", + "location": "Script Options > macOS/Linux/WSL table, CODEMIE_NPM_PREFIX row", + "problem": "Row says 'npm prefix used when `INSTALL_MODE` resolves to `user-prefix`' but no INSTALL_MODE variable exists — the documented env var is CODEMIE_INSTALL_MODE.", + "impact": "A user may set a non-existent INSTALL_MODE and the user-prefix mode silently fails to trigger.", + "recommendation": "Change `INSTALL_MODE` to `CODEMIE_INSTALL_MODE`." + }, + { + "id": "CR-002", + "triage": "patch", + "severity": "major", + "location": "macOS Installation Wizard > Log File", + "problem": "States as established fact that output goes to ~/Library/Logs/CodeMie/ (a directory), but the wizard source lives in a separate repo (codemie-claude-installer-mac) so this is unverifiable from here; the plan doc (docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md:597) specifies the FILE ~/Library/Logs/CodeMie/wizard.log.", + "impact": "Over-certain claim about a separate-repo artifact; directory-vs-file mismatch could mislead debugging.", + "recommendation": "Soften to attribution framing and reference the file path from the plan doc, e.g. 'Wizard output is written to ~/Library/Logs/CodeMie/wizard.log (per the macOS installer plan; the wizard source lives in a separate repository).'" + } + ] +} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff new file mode 100644 index 00000000..1e11b0b7 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff @@ -0,0 +1,116 @@ +diff --git a/install/README.md b/install/README.md +index 3b0daa3..55af67e 100644 +--- a/install/README.md ++++ b/install/README.md +@@ -1,6 +1,11 @@ + # CodeMie Bootstrap Installers + +-This directory contains source files for the lightweight CodeMie bootstrap installers. ++This directory contains source files for the CodeMie installers: ++ ++- **GUI installers** — a signed `.dmg` (macOS, Apple Silicon) and a `.exe` wizard (Windows) that install and configure CodeMie with no terminal required. ++- **Script installers** — plain shell/PowerShell bootstrap scripts that install via npm. Prefer these for CI, headless machines, or when a GUI installer is unavailable. ++ ++## Distribution Models + + Two distribution models are supported: + +@@ -9,12 +14,13 @@ Two distribution models are supported: + - Windows CMD: `install/windows/install.cmd` + - macOS/Linux/WSL: `install/macos/install.sh` + +-2. **Windows Installation Wizard** — a self-contained GUI installer: +- - `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` ++2. **GUI installers** — self-contained desktop applications: ++ - macOS: `install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` ++ - Windows: `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` + +-The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a Windows-built `.exe`. ++The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a GUI installer. + +-Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. ++Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. `CODEMIE_INSTALL_URL` points at the **directory** containing `install.ps1`, not the file itself. + + Channel selection is not implemented in the bootstrap scripts yet. Install the default npm package version, or pass an explicit version with PowerShell `-Version` or shell `CODEMIE_PACKAGE_VERSION`. + +@@ -48,11 +54,40 @@ https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/i + https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh + ``` + +-For reproducible installs, replace `main` with a release tag such as `v0.0.57`. ++For reproducible installs, replace `main` with a release tag such as `v0.8.0`. ++ ++## Script Options ++ ++### Windows PowerShell (`install/windows/install.ps1`) ++ ++| Parameter | Default | Values / Purpose | ++|---|---|---| ++| `-Mode` | `portable` | `portable` = npm prefix under `-InstallRoot` with shim `.cmd` files in `bin/` and a user PATH update; `npm-global` = plain `npm install -g` into the existing npm prefix | ++| `-Version` | *(empty)* | Pin `@codemieai/code` to a specific version | ++| `-RegistryUrl` | `https://registry.npmjs.org/` | npm registry used for resolution and install | ++| `-ScopeRegistryUrl` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | ++| `-InstallRoot` | `%LOCALAPPDATA%\CodeMie` | Portable install root (`-Mode portable` only) | ++| `-DryRun` | *(switch)* | Print every action without executing it | ++ ++### macOS / Linux / WSL (`install/macos/install.sh`) ++ ++| Env var | Default | Values / Purpose | ++|---|---|---| ++| `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | ++| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | ++| `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | ++| `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | ++| `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | ++ ++Pin a version on macOS/Linux/WSL: ++ ++```bash ++curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | env CODEMIE_PACKAGE_VERSION=0.8.0 bash ++``` + + ## Windows Defaults + +-Windows installs into the current user's local profile by default: ++Windows installs into the current user's local profile by default (`-Mode portable`): + + ```text + %LOCALAPPDATA%\CodeMie +@@ -64,7 +99,7 @@ Known limitation: `install/windows/install.cmd` forwards arguments to PowerShell + + ## macOS/Linux Defaults + +-macOS, Linux, and WSL prefer npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix. ++macOS, Linux, and WSL use `CODEMIE_INSTALL_MODE=auto` by default: npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix (`$HOME/.codemie/npm-prefix`). + + ## Windows Installation Wizard + +@@ -118,6 +153,28 @@ All wizard output is written to: + + The log persists across runs. Each line is prefixed with an ISO-8601 timestamp and a tag: `[OUT]` stdout, `[ERR]` stderr, `[INF]` info, `[OK]` success, `[CMD]` command. + ++## macOS Installation Wizard ++ ++`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` is a signed macOS desktop GUI application for **Apple Silicon (aarch64)** Macs. It installs and configures the CodeMie CLI and Claude engine end-to-end with no terminal required. (An Intel x86_64 build is not shipped.) ++ ++The wizard is built from a separate repository (`codemie-claude-installer-mac`); the `.dmg` committed here is the distributed artifact. ++ ++### Running the Wizard ++ ++Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install folder](https://github.com/codemie-ai/codemie-code/tree/main/install/macos), open it, and run the app. The wizard walks the user through installing prerequisites (Xcode Command Line Tools, Node.js, Git), the CodeMie CLI, an interactive `codemie setup`, the Claude engine via `codemie install claude`, and a final `codemie doctor` validation. ++ ++### Log File ++ ++Wizard output is written to: ++ ++```text ++~/Library/Logs/CodeMie/ ++``` ++ ++The log persists across runs. ++ ++> The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. ++ + ## Release Artifacts + + Run this command to prepare publishable artifacts: diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json new file mode 100644 index 00000000..f4499248 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json @@ -0,0 +1,16 @@ +{ + "schema": 1, + "runner": "npm", + "gates": [ + {"id": "license-check", "command": "npm run license-check", "available": true}, + {"id": "lint", "command": "npm run lint", "available": true}, + {"id": "typecheck", "command": "npm run typecheck", "available": true}, + {"id": "build", "command": "npm run build", "available": true}, + {"id": "unit", "command": "npm run test:unit", "available": true}, + {"id": "integration", "command": "npm run test:integration", "available": true}, + {"id": "affected", "command": "", "available": false}, + {"id": "ui", "command": "", "available": false} + ], + "ui_globs": ["\\.(tsx|jsx|css|html|vue|svelte)$", "src/(ui|frontend|components)/"], + "detected_at": "2026-07-03T14:10:00Z" +} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md new file mode 100644 index 00000000..25e1dad8 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md @@ -0,0 +1,273 @@ +# Update install/README.md — Implementation Plan + +> **For agentic workers:** This is an sdlc-light run. Implementation is inline (Stage 4), no subagents. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Bring `install/README.md` in sync with the actual contents of `install/` — primarily by documenting the missing macOS `.dmg` GUI installer and the script parameters/env-vars. + +**Architecture:** Single-file docs rewrite. No code, no scripts, no tests. Preserve all accurate existing content verbatim; add missing sections; refresh the one stale value (example release tag `v0.0.57` → `v0.8.0`). + +**Tech Stack:** Markdown only. + +**Test-first: no** for every task below — this is documentation; there is no behavior to assert with a failing test. Verification is read-through + grep checks that every script param/env-var is mentioned. + +## Clarification assumptions +- macOS wizard section is kept factual (existence, platform, signed, download/browse URLs, high-level step list grounded in the completed plan doc `docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md`). Its sources live in a separate repo (`codemie-claude-installer-mac`), so no fabricated detail beyond what is verifiable from this repo. +- Example release tag refreshed to `v0.8.0` to match `package.json` version. (Top-level `README.md` carries the same stale `v0.0.57` examples but is out of scope.) + +## File Structure +- Modify (only file touched): `install/README.md` + +No other files change. `artifacts/install/manifest.json` (still `0.0.57`) is a generated artifact and is out of scope. + +--- + +### Task 1: Rewrite `install/README.md` with all drift fixes + +**Files:** +- Modify: `install/README.md` (full rewrite via `Write`) + +**Drift fixed in this single deliverable** (from `technical-analysis.md`): +1. Add macOS `.dmg` GUI installer to intro + distribution list + new "macOS Installation Wizard" section. +2. Add full PowerShell `install.ps1` parameter table (`-Mode`, `-Version`, `-RegistryUrl`, `-ScopeRegistryUrl`, `-InstallRoot`, `-DryRun`). +3. Add full shell `install.sh` env-var table (`CODEMIE_REGISTRY_URL`, `CODEMIE_SCOPE_REGISTRY_URL`, `CODEMIE_INSTALL_MODE`, `CODEMIE_NPM_PREFIX`, `CODEMIE_PACKAGE_VERSION`). +4. Refresh stale example tag `v0.0.57` → `v0.8.0` (lines 51). +5. Clarify Windows `portable` vs macOS `auto` install modes by naming them. +6. Keep Windows wizard / Release Artifacts / Defaults sections verbatim. + +- [ ] **Step 1: Write the new `install/README.md`** + +Full target content (replace entire file): + +````markdown +# CodeMie Bootstrap Installers + +This directory contains source files for the CodeMie installers: + +- **GUI installers** — a signed `.dmg` (macOS, Apple Silicon) and a `.exe` wizard (Windows) that install and configure CodeMie with no terminal required. +- **Script installers** — plain shell/PowerShell bootstrap scripts that install via npm. Prefer these for CI, headless machines, or when a GUI installer is unavailable. + +## Distribution Models + +Two distribution models are supported: + +1. **Hosted scripts** — run directly from GitHub raw URLs or mirror to Artifactory: + - Windows PowerShell: `install/windows/install.ps1` + - Windows CMD: `install/windows/install.cmd` + - macOS/Linux/WSL: `install/macos/install.sh` + +2. **GUI installers** — self-contained desktop applications: + - macOS: `install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` + - Windows: `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` + +The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a GUI installer. + +Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. `CODEMIE_INSTALL_URL` points at the **directory** containing `install.ps1`, not the file itself. + +Channel selection is not implemented in the bootstrap scripts yet. Install the default npm package version, or pass an explicit version with PowerShell `-Version` or shell `CODEMIE_PACKAGE_VERSION`. + +## GitHub Raw URLs + +Use `main` for the latest installer source. + +Windows PowerShell: + +```powershell +irm https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.ps1 | iex +``` + +Windows CMD: + +```cmd +curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.cmd -o install.cmd && install.cmd && del install.cmd +``` + +macOS, Linux, and WSL: + +```bash +curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | bash +``` + +Direct file URLs: + +```text +https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.ps1 +https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.cmd +https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh +``` + +For reproducible installs, replace `main` with a release tag such as `v0.8.0`. + +## Script Options + +### Windows PowerShell (`install/windows/install.ps1`) + +| Parameter | Default | Values / Purpose | +|---|---|---| +| `-Mode` | `portable` | `portable` = npm prefix under `-InstallRoot` with shim `.cmd` files in `bin/` and a user PATH update; `npm-global` = plain `npm install -g` into the existing npm prefix | +| `-Version` | *(empty)* | Pin `@codemieai/code` to a specific version | +| `-RegistryUrl` | `https://registry.npmjs.org/` | npm registry used for resolution and install | +| `-ScopeRegistryUrl` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | +| `-InstallRoot` | `%LOCALAPPDATA%\CodeMie` | Portable install root (`-Mode portable` only) | +| `-DryRun` | *(switch)* | Print every action without executing it | + +### macOS / Linux / WSL (`install/macos/install.sh`) + +| Env var | Default | Values / Purpose | +|---|---|---| +| `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | +| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | +| `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | +| `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | +| `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | + +Pin a version on macOS/Linux/WSL: + +```bash +curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | env CODEMIE_PACKAGE_VERSION=0.8.0 bash +``` + +## Windows Defaults + +Windows installs into the current user's local profile by default (`-Mode portable`): + +```text +%LOCALAPPDATA%\CodeMie +``` + +The installer calls `npm.cmd` directly to avoid PowerShell resolving `npm` to `npm.ps1`. + +Known limitation: `install/windows/install.cmd` forwards arguments to PowerShell through `%*`. Use the PowerShell installer directly when passing arguments that contain spaces, such as `-InstallRoot "C:\My Folder"`. + +## macOS/Linux Defaults + +macOS, Linux, and WSL use `CODEMIE_INSTALL_MODE=auto` by default: npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix (`$HOME/.codemie/npm-prefix`). + +## Windows Installation Wizard + +`install/windows/CodeMie Connect_2.0.1_x64-setup.exe` is a self-contained Windows desktop GUI application that installs and configures the CodeMie Claude Code CLI end-to-end. It requires no terminal knowledge and bundles all dependencies. + +### Running the Wizard + +Double-click `CodeMie Connect_2.0.1_x64-setup.exe`. No command-line arguments are supported — the wizard is a pure GUI application. + +The wizard walks through the following steps in order: + +| Step | What it does | +|------|-------------| +| PowerShell execution policy | Sets `RemoteSigned` scope for the current user | +| Git for Windows | Detects an existing install or silently downloads and installs v2.47.0-64-bit | +| Node.js + npm | Detects an existing install or silently downloads and installs Node.js LTS v20.18.0 | +| CodeMie CLI | Installs `@codemieai/code` globally via `npm install -g` | +| CodeMie setup | Opens a visible terminal window and runs `codemie setup` interactively | +| Claude engine | Opens a visible terminal window and runs `codemie install claude --supported` | +| Validation | Runs `codemie doctor` to confirm everything is working | + +Each step that requires a download shows a progress animation and an inline **Approve** / **Ignore** button before proceeding. + +### Unattended Mode + +Check the **Unattended mode** checkbox in the left sidebar before clicking Install. All approval gates auto-approve, so the wizard runs without prompts. The two interactive terminal steps (`codemie setup` and `codemie install claude`) still open a visible console window because they require user input. + +### Default Paths + +Tools are installed to their standard system locations: + +```text +Git: C:\Program Files\Git\cmd\git.exe +Node: C:\Program Files\nodejs\node.exe +``` + +npm global binaries are added to the current user's `PATH`: + +```text +%USERPROFILE%\AppData\Local\CodeMie\npm-prefix +%USERPROFILE%\AppData\Roaming\npm +``` + +### Log File + +All wizard output is written to: + +```text +%TEMP%\codemie_wizard.log +``` + +The log persists across runs. Each line is prefixed with an ISO-8601 timestamp and a tag: `[OUT]` stdout, `[ERR]` stderr, `[INF]` info, `[OK]` success, `[CMD]` command. + +## macOS Installation Wizard + +`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` is a signed macOS desktop GUI application for **Apple Silicon (aarch64)** Macs. It installs and configures the CodeMie CLI and Claude engine end-to-end with no terminal required. (An Intel x86_64 build is not shipped.) + +The wizard is built from a separate repository (`codemie-claude-installer-mac`); the `.dmg` committed here is the distributed artifact. + +### Running the Wizard + +Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install folder](https://github.com/codemie-ai/codemie-code/tree/main/install/macos), open it, and run the app. The wizard walks the user through installing prerequisites (Xcode Command Line Tools, Node.js, Git), the CodeMie CLI, an interactive `codemie setup`, the Claude engine via `codemie install claude`, and a final `codemie doctor` validation. + +### Log File + +Wizard output is written to: + +```text +~/Library/Logs/CodeMie/ +``` + +The log persists across runs. + +> The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. + +## Release Artifacts + +Run this command to prepare publishable artifacts: + +```bash +npm run prepare:install-artifacts +``` + +Generated files are written to `artifacts/install/` and are not committed. + +Generated artifacts include a version header and their checksums are computed from the generated artifact content, not from the source files under `install/`. +```` + +- [ ] **Step 2: Verify all script params/env-vars are documented** + +Run these greps — each must return at least one match in `install/README.md`: + +```bash +grep -c 'Mode' install/README.md # PowerShell -Mode +grep -c 'DryRun' install/README.md # PowerShell -DryRun +grep -c 'INSTALL_MODE' install/README.md # shell CODEMIE_INSTALL_MODE +grep -c 'NPM_PREFIX' install/README.md # shell CODEMIE_NPM_PREFIX +grep -c 'aarch64' install/README.md # macOS dmg +grep -c 'v0.8.0' install/README.md # refreshed tag +grep -c 'Library/Logs/CodeMie' install/README.md # macOS log path +``` + +Expected: every count `>= 1`. Also confirm the stale tag is gone: + +```bash +grep -c 'v0.0.57' install/README.md # must be 0 +``` + +- [ ] **Step 3: Commit** + +```bash +git add install/README.md +git commit -m "docs(install): document macOS dmg installer and script options in README" +``` + +--- + +## Self-Review + +**Spec coverage (drift items from technical-analysis.md):** +- Drift 1 (macOS dmg undocumented) → Task 1: new "macOS Installation Wizard" section + intro/distribution list entries. ✅ +- Drift 2 (PowerShell params) → Task 1: "Script Options → Windows PowerShell" table, all 6 params. ✅ +- Drift 3 (shell env vars) → Task 1: "Script Options → macOS/Linux/WSL" table, all 5 vars. ✅ +- Drift 4 (stale tag) → Task 1: `v0.0.57` → `v0.8.0`. ✅ +- Drift 5 (mode asymmetry) → Task 1: modes named (`portable`, `auto`/`npm-global`/`user-prefix`) in Defaults + Script Options. ✅ +- Drift 6 (CMD wrapper) → Task 1: clarified `CODEMIE_INSTALL_URL` points at the directory. ✅ + +**Placeholder scan:** none. Full target file content is inline. + +**Type/name consistency:** filenames and URLs match the actual folder contents (`CodeMie Connect_2.0.1_aarch64_signed.dmg`, `install/macos/install.sh`, etc.). diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md new file mode 100644 index 00000000..9fbe4dcc --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md @@ -0,0 +1,32 @@ +# QA Gate Report — update-install-readme + +**Branch**: docs/install-readme-update +**Runner**: npm +**Started**: 2026-07-03T14:10:00Z +**Status**: PASSED + +## Changed files (vs merge_base da7d0df) +- `install/README.md` (docs-only; Markdown) + +## Gates + +| Gate | Status | Duration | Command | Notes | +|------|--------|----------|---------|-------| +| license-check | N/A | — | `npm run license-check` | scans `src/` Apache headers; no `src/` file touched | +| lint | PASS | ~8s | `npm run lint` | exit 0, zero warnings; scope `{src,tests}/**/*.ts` (no .ts touched, whole-project clean) | +| typecheck | PASS | ~3s | `npm run typecheck` | exit 0, no diagnostics | +| build | SKIPPED | — | `npm run build` | guide Skip-if: "pure docs" edits — change is a single `.md` | +| unit | SKIPPED | — | `npm run test:unit` | guide Skip-if: doc-only change | +| integration | SKIPPED | — | `npm run test:integration` | no integration coverage of a README; doc-only | +| secrets | PASS | — | `npm run validate:secrets` | ran via pre-commit hook on both commits; no leaks | +| commitlint | PASS | — | `npm run commitlint:last` | enforced by commit-msg hook on both commits; scope `cli` valid | +| ui | SKIPPED | — | (n/a) | no UI surface changed (`.md` only) | + +## Failure detail (if any) +None. + +## Drift signal +no — implementation matches plan; code review (final + check) passed. + +## Outcome +PASSED. All in-scope gates green; doc-only skip-eligible gates skipped per `.ai-run/guides/quality-gates.md`. diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md new file mode 100644 index 00000000..50de3344 --- /dev/null +++ b/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md @@ -0,0 +1,75 @@ +# Technical Analysis — update-install-readme + +## Task +Update `install/README.md` so it accurately reflects the actual contents of the `install/` folder. The README is out of date. + +## Scope +Docs-only change. Single file: `install/README.md`. No code, no scripts, no behavior change. + +## Codebase Findings + +### Folder contents (ground truth) +`install/` contains exactly six entries: + +| Path | Type | Documented in README? | +|---|---|---| +| `README.md` | doc | (self) | +| `macos/install.sh` | shell bootstrap script | ✅ partially | +| `macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` | macOS GUI installer (signed, Apple Silicon) | ❌ **missing entirely** | +| `windows/install.ps1` | PowerShell bootstrap script | ✅ partially | +| `windows/install.cmd` | CMD wrapper | ✅ | +| `windows/CodeMie Connect_2.0.1_x64-setup.exe` | Windows GUI wizard | ✅ detailed | + +### Drift item 1 — macOS `.dmg` installer undocumented (major) +`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` (2.6 MB, signed, aarch64/Apple Silicon) has **zero coverage** in `install/README.md`. The top-level `README.md:71` documents it as a GUI installer option, but `install/README.md`'s only "Installation Wizard" section covers Windows exclusively. +- The macOS wizard is a SwiftUI app built in a **separate repository** (`codemie-claude-installer-mac`; per `docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md`). Its step list / log path are not verifiable from this repo. +- Verifiable facts: filename, signed, aarch64 (Apple Silicon) only, GUI/no-terminal, download/browse URLs. + +### Drift item 2 — PowerShell `install.ps1` parameters underdocumented +The README mentions only `-Version` and `-InstallRoot`. Actual parameters (`install.ps1:2-9`): + +| Param | Values / default | Purpose | +|---|---|---| +| `-Mode` | `portable` (default) \| `npm-global` | portable = npm prefix under InstallRoot + shim `.cmd`s in `bin/`; npm-global = plain `npm install -g` | +| `-Version` | string, default `''` | pin package version | +| `-RegistryUrl` | default `https://registry.npmjs.org/` | npm registry | +| `-ScopeRegistryUrl` | default `''` | sets `@codemieai:registry` | +| `-InstallRoot` | default `%LOCALAPPDATA%\CodeMie` | portable install root | +| `-DryRun` | switch | print actions, execute nothing | + +### Drift item 3 — Shell `install.sh` env vars underdocumented +README mentions only `CODEMIE_PACKAGE_VERSION` (and `CODEMIE_INSTALL_URL` for the CMD wrapper). Actual env vars (`install.sh:6-10`): + +| Env var | Values / default | Purpose | +|---|---|---| +| `CODEMIE_REGISTRY_URL` | default `https://registry.npmjs.org/` | npm registry | +| `CODEMIE_SCOPE_REGISTRY_URL` | default `''` | sets `@codemieai:registry` | +| `CODEMIE_INSTALL_MODE` | `auto` (default) \| `npm-global` \| `user-prefix` | auto picks npm-global if prefix writable, else user-prefix | +| `CODEMIE_NPM_PREFIX` | default `$HOME/.codemie/npm-prefix` | user-prefix target | +| `CODEMIE_PACKAGE_VERSION` | default `''` | pin package version | + +### Drift item 4 — stale version example +README pins the example release tag to `v0.0.57` (lines 51, 86 equivalent). `package.json` version is now `0.8.0`. Example tag should be refreshed to `v0.8.0`. (The top-level `README.md` carries the same stale `v0.0.57` examples, but that file is out of scope here.) + +### Drift item 5 — install-mode asymmetry unexplained +Windows default = `portable` mode (npm prefix + 7 shim `.cmd` files under `bin/`, PATH update). macOS/Linux default = `auto` (npm-global if writable, else user-prefix with `$HOME/.codemie/npm-prefix`). README describes both behaviors but never names the modes or maps them to the script params/env vars, so the two columns read as inconsistent rather than symmetric. + +### Drift item 6 — CMD wrapper behavior +`install/windows/install.cmd` (verified): defaults `CODEMIE_INSTALL_URL` to `https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows`, `curl`s `install.ps1` to `%TEMP%`, executes it, deletes it. README's CMD section is accurate but light on the `CODEMIE_INSTALL_URL` override semantics (it overrides the **directory**, not the file). + +### Accurate content to preserve +- GitHub raw URL section (lines 21–51) — correct, just needs tag refresh. +- Windows Defaults section (`%LOCALAPPDATA%\CodeMie`, `npm.cmd` direct call, `%*` forwarding limitation) — accurate. +- macOS/Linux Defaults paragraph — accurate. +- Windows Installation Wizard section (steps table, unattended mode, default paths, log file) — authoritative; preserve as-is. +- Release Artifacts section — accurate (`npm run prepare:install-artifacts` → `artifacts/install/`, checksums from generated content). + +## Risk Indicators +- **Binary `.dmg`/`.exe` in repo** — README must not claim behaviors verifiable only from the (separate-repo) wizard sources. Keep macOS wizard section factual. +- **Version-pinned filenames** (`CodeMie Connect_2.0.1_*`) drift from npm package version (`0.8.0`) — different versioning schemes; README should state the wizard version as part of the filename, not imply it equals the npm version. +- **`artifacts/install/manifest.json`** still shows `packageVersion: 0.0.57` — generated artifact, out of scope for this README fix; do not "fix" it. + +## Orchestrator Digest +Single-file docs update with clear, codebase-grounded drift list. No ambiguity in *what* to fix; the only judgment call is how much detail to give the macOS wizard given its sources live in another repo — recommendation is a factual minimal section (existence, platform, signed, download/browse link) mirroring the top-level README's treatment, not a fabricated step table. No code, no tests, no scripts touched. + +**Open questions:** none blocking — proceeding with the minimal-but-factual macOS wizard section and a consolidated script-options reference table. From e9e3c85e7d88a40ab6beb86ce9986b0040e0e5c7 Mon Sep 17 00:00:00 2001 From: vadimvlasenko Date: Mon, 6 Jul 2026 10:49:38 +0300 Subject: [PATCH 4/4] feat: update md docs --- .../actual-complexity.json | 17 -- .../code-review-check.diff | 28 -- .../code-review-check.json | 24 -- .../code-review-final.json | 39 --- .../code-review.diff | 116 -------- .../gate-plan.json | 16 - .../2026-07-03-update-install-readme/plan.md | 273 ------------------ .../qa-report.md | 32 -- .../technical-analysis.md | 75 ----- 9 files changed, 620 deletions(-) delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md delete mode 100644 docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json deleted file mode 100644 index 1d7d1b82..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/actual-complexity.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "mode": "actual", - "size": "XS", - "total": 6, - "dimensions": { - "files_changed": {"score": 1, "note": "1 file (install/README.md)"}, - "lines_changed": {"score": 1, "note": "59 insertions, 8 deletions"}, - "architecture_surface": {"score": 1, "note": "no code; documentation only"}, - "test_surface": {"score": 1, "note": "no tests; docs-only, no behavior to assert"}, - "risk": {"score": 1, "note": "no security/auth/migration/breaking surface; docs change"}, - "cross_layer": {"score": 1, "note": "single file, no layer crossings"} - }, - "diffstat": "1 file changed, 59 insertions(+), 8 deletions(-)", - "changed_files": ["install/README.md"], - "assessed_at": "2026-07-03T14:12:00Z", - "note": "Assessed inline: complexity-assessor subagent unavailable (codegraph MCP not connected). Score reflects direct inspection — 1 docs file, low-risk, no code/tests/layers." -} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff deleted file mode 100644 index 7b800959..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.diff +++ /dev/null @@ -1,28 +0,0 @@ -diff --git a/install/README.md b/install/README.md -index 55af67e..cf9b698 100644 ---- a/install/README.md -+++ b/install/README.md -@@ -74,7 +74,7 @@ For reproducible installs, replace `main` with a release tag such as `v0.8.0`. - | Env var | Default | Values / Purpose | - |---|---|---| - | `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | --| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | -+| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `CODEMIE_INSTALL_MODE` resolves to `user-prefix` | - | `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | - | `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | - | `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | -@@ -165,13 +165,7 @@ Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install fold - - ### Log File - --Wizard output is written to: -- --```text --~/Library/Logs/CodeMie/ --``` -- --The log persists across runs. -+Wizard output is written to `~/Library/Logs/CodeMie/wizard.log` (per the macOS installer plan; the wizard source lives in a separate repository). The log persists across runs. - - > The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. - diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json deleted file mode 100644 index 80ba322e..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-check.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "decision": "approve", - "rationale": "Check round re-verified both blocking findings against the fix-up diff. CR-001 resolved: CODEMIE_NPM_PREFIX row now reads 'CODEMIE_INSTALL_MODE resolves to user-prefix' — matches the documented env var. CR-002 resolved: macOS log path softened to attribution framing with the plan doc's file path (~/Library/Logs/CodeMie/wizard.log), no longer stated as unverifiable certainty. Fix-up diff is 2+/8- on the same single file, introduces no new high-risk issue (docs-only, no security/API/runtime surface). business_review and standards_review carried forward unchanged from the final round.", - "confidence": "high", - "risk_flags": [], - "business_review": [ - {"criterion": "1. macOS .dmg in intro + distribution list + new wizard section", "status": "pass"}, - {"criterion": "2. Full PowerShell install.ps1 parameter table", "status": "pass"}, - {"criterion": "3. Full install.sh env-var table", "status": "pass"}, - {"criterion": "4. Refresh stale tag v0.0.57 -> v0.8.0", "status": "pass"}, - {"criterion": "5. Name Windows portable vs macOS auto modes", "status": "pass"}, - {"criterion": "6. Keep Windows wizard / Release Artifacts / Defaults verbatim", "status": "partial", "notes": "Wizard + Release Artifacts byte-identical; Defaults prose edited to satisfy criterion 5 — resolved by design"} - ], - "standards_review": [ - {"check": "commit-format", "status": "pass", "notes": "docs(cli): ... matches Conventional Commits; scope 'cli' in allowed enum"}, - {"check": "code-quality", "status": "na", "notes": "docs-only change, no code"}, - {"check": "security", "status": "na", "notes": "docs-only, no credentials/paths/injection surface"} - ], - "findings": [], - "finding_status": [ - {"id": "CR-001", "status": "resolved", "evidence": "fix-up diff line: '+| CODEMIE_NPM_PREFIX | $HOME/.codemie/npm-prefix | npm prefix used when CODEMIE_INSTALL_MODE resolves to user-prefix |'"}, - {"id": "CR-002", "status": "resolved", "evidence": "fix-up diff replaces the over-certain directory path with 'Wizard output is written to ~/Library/Logs/CodeMie/wizard.log (per the macOS installer plan; the wizard source lives in a separate repository).'"} - ] -} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json deleted file mode 100644 index 0345f00a..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review-final.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "decision": "request-changes", - "rationale": "All 3 lenses ran; 5/6 acceptance criteria pass. Two major patch findings: a typo referencing a non-existent INSTALL_MODE variable (CR-001) and an over-certain macOS log-path claim that is unverifiable from this repo and mismatches the plan doc's file path (CR-002). Both are small factual fixes. Acceptance criterion 6 (verbatim preservation) is partial because the Defaults prose was edited to satisfy criterion 5 (name the modes) — resolved by design; substantive wizard/artifacts content is byte-identical.", - "confidence": "medium", - "risk_flags": [], - "business_review": [ - {"criterion": "1. macOS .dmg in intro + distribution list + new wizard section", "status": "pass"}, - {"criterion": "2. Full PowerShell install.ps1 parameter table", "status": "pass"}, - {"criterion": "3. Full install.sh env-var table", "status": "pass"}, - {"criterion": "4. Refresh stale tag v0.0.57 -> v0.8.0", "status": "pass"}, - {"criterion": "5. Name Windows portable vs macOS auto modes", "status": "pass"}, - {"criterion": "6. Keep Windows wizard / Release Artifacts / Defaults verbatim", "status": "partial", "notes": "Wizard + Release Artifacts byte-identical; Defaults prose edited to satisfy criterion 5 — resolved by design"} - ], - "standards_review": [ - {"check": "commit-format", "status": "pass", "notes": "docs(cli): ... matches Conventional Commits; scope 'cli' is in allowed enum (install was not)"}, - {"check": "code-quality", "status": "na", "notes": "docs-only change, no code"}, - {"check": "security", "status": "na", "notes": "docs-only, no credentials/paths/injection surface"} - ], - "findings": [ - { - "id": "CR-001", - "triage": "patch", - "severity": "major", - "location": "Script Options > macOS/Linux/WSL table, CODEMIE_NPM_PREFIX row", - "problem": "Row says 'npm prefix used when `INSTALL_MODE` resolves to `user-prefix`' but no INSTALL_MODE variable exists — the documented env var is CODEMIE_INSTALL_MODE.", - "impact": "A user may set a non-existent INSTALL_MODE and the user-prefix mode silently fails to trigger.", - "recommendation": "Change `INSTALL_MODE` to `CODEMIE_INSTALL_MODE`." - }, - { - "id": "CR-002", - "triage": "patch", - "severity": "major", - "location": "macOS Installation Wizard > Log File", - "problem": "States as established fact that output goes to ~/Library/Logs/CodeMie/ (a directory), but the wizard source lives in a separate repo (codemie-claude-installer-mac) so this is unverifiable from here; the plan doc (docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md:597) specifies the FILE ~/Library/Logs/CodeMie/wizard.log.", - "impact": "Over-certain claim about a separate-repo artifact; directory-vs-file mismatch could mislead debugging.", - "recommendation": "Soften to attribution framing and reference the file path from the plan doc, e.g. 'Wizard output is written to ~/Library/Logs/CodeMie/wizard.log (per the macOS installer plan; the wizard source lives in a separate repository).'" - } - ] -} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff b/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff deleted file mode 100644 index 1e11b0b7..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/code-review.diff +++ /dev/null @@ -1,116 +0,0 @@ -diff --git a/install/README.md b/install/README.md -index 3b0daa3..55af67e 100644 ---- a/install/README.md -+++ b/install/README.md -@@ -1,6 +1,11 @@ - # CodeMie Bootstrap Installers - --This directory contains source files for the lightweight CodeMie bootstrap installers. -+This directory contains source files for the CodeMie installers: -+ -+- **GUI installers** — a signed `.dmg` (macOS, Apple Silicon) and a `.exe` wizard (Windows) that install and configure CodeMie with no terminal required. -+- **Script installers** — plain shell/PowerShell bootstrap scripts that install via npm. Prefer these for CI, headless machines, or when a GUI installer is unavailable. -+ -+## Distribution Models - - Two distribution models are supported: - -@@ -9,12 +14,13 @@ Two distribution models are supported: - - Windows CMD: `install/windows/install.cmd` - - macOS/Linux/WSL: `install/macos/install.sh` - --2. **Windows Installation Wizard** — a self-contained GUI installer: -- - `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` -+2. **GUI installers** — self-contained desktop applications: -+ - macOS: `install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` -+ - Windows: `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` - --The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a Windows-built `.exe`. -+The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a GUI installer. - --Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. -+Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. `CODEMIE_INSTALL_URL` points at the **directory** containing `install.ps1`, not the file itself. - - Channel selection is not implemented in the bootstrap scripts yet. Install the default npm package version, or pass an explicit version with PowerShell `-Version` or shell `CODEMIE_PACKAGE_VERSION`. - -@@ -48,11 +54,40 @@ https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/i - https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh - ``` - --For reproducible installs, replace `main` with a release tag such as `v0.0.57`. -+For reproducible installs, replace `main` with a release tag such as `v0.8.0`. -+ -+## Script Options -+ -+### Windows PowerShell (`install/windows/install.ps1`) -+ -+| Parameter | Default | Values / Purpose | -+|---|---|---| -+| `-Mode` | `portable` | `portable` = npm prefix under `-InstallRoot` with shim `.cmd` files in `bin/` and a user PATH update; `npm-global` = plain `npm install -g` into the existing npm prefix | -+| `-Version` | *(empty)* | Pin `@codemieai/code` to a specific version | -+| `-RegistryUrl` | `https://registry.npmjs.org/` | npm registry used for resolution and install | -+| `-ScopeRegistryUrl` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | -+| `-InstallRoot` | `%LOCALAPPDATA%\CodeMie` | Portable install root (`-Mode portable` only) | -+| `-DryRun` | *(switch)* | Print every action without executing it | -+ -+### macOS / Linux / WSL (`install/macos/install.sh`) -+ -+| Env var | Default | Values / Purpose | -+|---|---|---| -+| `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | -+| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | -+| `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | -+| `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | -+| `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | -+ -+Pin a version on macOS/Linux/WSL: -+ -+```bash -+curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | env CODEMIE_PACKAGE_VERSION=0.8.0 bash -+``` - - ## Windows Defaults - --Windows installs into the current user's local profile by default: -+Windows installs into the current user's local profile by default (`-Mode portable`): - - ```text - %LOCALAPPDATA%\CodeMie -@@ -64,7 +99,7 @@ Known limitation: `install/windows/install.cmd` forwards arguments to PowerShell - - ## macOS/Linux Defaults - --macOS, Linux, and WSL prefer npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix. -+macOS, Linux, and WSL use `CODEMIE_INSTALL_MODE=auto` by default: npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix (`$HOME/.codemie/npm-prefix`). - - ## Windows Installation Wizard - -@@ -118,6 +153,28 @@ All wizard output is written to: - - The log persists across runs. Each line is prefixed with an ISO-8601 timestamp and a tag: `[OUT]` stdout, `[ERR]` stderr, `[INF]` info, `[OK]` success, `[CMD]` command. - -+## macOS Installation Wizard -+ -+`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` is a signed macOS desktop GUI application for **Apple Silicon (aarch64)** Macs. It installs and configures the CodeMie CLI and Claude engine end-to-end with no terminal required. (An Intel x86_64 build is not shipped.) -+ -+The wizard is built from a separate repository (`codemie-claude-installer-mac`); the `.dmg` committed here is the distributed artifact. -+ -+### Running the Wizard -+ -+Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install folder](https://github.com/codemie-ai/codemie-code/tree/main/install/macos), open it, and run the app. The wizard walks the user through installing prerequisites (Xcode Command Line Tools, Node.js, Git), the CodeMie CLI, an interactive `codemie setup`, the Claude engine via `codemie install claude`, and a final `codemie doctor` validation. -+ -+### Log File -+ -+Wizard output is written to: -+ -+```text -+~/Library/Logs/CodeMie/ -+``` -+ -+The log persists across runs. -+ -+> The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. -+ - ## Release Artifacts - - Run this command to prepare publishable artifacts: diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json b/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json deleted file mode 100644 index f4499248..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/gate-plan.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "schema": 1, - "runner": "npm", - "gates": [ - {"id": "license-check", "command": "npm run license-check", "available": true}, - {"id": "lint", "command": "npm run lint", "available": true}, - {"id": "typecheck", "command": "npm run typecheck", "available": true}, - {"id": "build", "command": "npm run build", "available": true}, - {"id": "unit", "command": "npm run test:unit", "available": true}, - {"id": "integration", "command": "npm run test:integration", "available": true}, - {"id": "affected", "command": "", "available": false}, - {"id": "ui", "command": "", "available": false} - ], - "ui_globs": ["\\.(tsx|jsx|css|html|vue|svelte)$", "src/(ui|frontend|components)/"], - "detected_at": "2026-07-03T14:10:00Z" -} diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md deleted file mode 100644 index 25e1dad8..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/plan.md +++ /dev/null @@ -1,273 +0,0 @@ -# Update install/README.md — Implementation Plan - -> **For agentic workers:** This is an sdlc-light run. Implementation is inline (Stage 4), no subagents. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Bring `install/README.md` in sync with the actual contents of `install/` — primarily by documenting the missing macOS `.dmg` GUI installer and the script parameters/env-vars. - -**Architecture:** Single-file docs rewrite. No code, no scripts, no tests. Preserve all accurate existing content verbatim; add missing sections; refresh the one stale value (example release tag `v0.0.57` → `v0.8.0`). - -**Tech Stack:** Markdown only. - -**Test-first: no** for every task below — this is documentation; there is no behavior to assert with a failing test. Verification is read-through + grep checks that every script param/env-var is mentioned. - -## Clarification assumptions -- macOS wizard section is kept factual (existence, platform, signed, download/browse URLs, high-level step list grounded in the completed plan doc `docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md`). Its sources live in a separate repo (`codemie-claude-installer-mac`), so no fabricated detail beyond what is verifiable from this repo. -- Example release tag refreshed to `v0.8.0` to match `package.json` version. (Top-level `README.md` carries the same stale `v0.0.57` examples but is out of scope.) - -## File Structure -- Modify (only file touched): `install/README.md` - -No other files change. `artifacts/install/manifest.json` (still `0.0.57`) is a generated artifact and is out of scope. - ---- - -### Task 1: Rewrite `install/README.md` with all drift fixes - -**Files:** -- Modify: `install/README.md` (full rewrite via `Write`) - -**Drift fixed in this single deliverable** (from `technical-analysis.md`): -1. Add macOS `.dmg` GUI installer to intro + distribution list + new "macOS Installation Wizard" section. -2. Add full PowerShell `install.ps1` parameter table (`-Mode`, `-Version`, `-RegistryUrl`, `-ScopeRegistryUrl`, `-InstallRoot`, `-DryRun`). -3. Add full shell `install.sh` env-var table (`CODEMIE_REGISTRY_URL`, `CODEMIE_SCOPE_REGISTRY_URL`, `CODEMIE_INSTALL_MODE`, `CODEMIE_NPM_PREFIX`, `CODEMIE_PACKAGE_VERSION`). -4. Refresh stale example tag `v0.0.57` → `v0.8.0` (lines 51). -5. Clarify Windows `portable` vs macOS `auto` install modes by naming them. -6. Keep Windows wizard / Release Artifacts / Defaults sections verbatim. - -- [ ] **Step 1: Write the new `install/README.md`** - -Full target content (replace entire file): - -````markdown -# CodeMie Bootstrap Installers - -This directory contains source files for the CodeMie installers: - -- **GUI installers** — a signed `.dmg` (macOS, Apple Silicon) and a `.exe` wizard (Windows) that install and configure CodeMie with no terminal required. -- **Script installers** — plain shell/PowerShell bootstrap scripts that install via npm. Prefer these for CI, headless machines, or when a GUI installer is unavailable. - -## Distribution Models - -Two distribution models are supported: - -1. **Hosted scripts** — run directly from GitHub raw URLs or mirror to Artifactory: - - Windows PowerShell: `install/windows/install.ps1` - - Windows CMD: `install/windows/install.cmd` - - macOS/Linux/WSL: `install/macos/install.sh` - -2. **GUI installers** — self-contained desktop applications: - - macOS: `install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` - - Windows: `install/windows/CodeMie Connect_2.0.1_x64-setup.exe` - -The scripts can be run directly from GitHub raw URLs or mirrored to Artifactory later. They do not require a GUI installer. - -Set `CODEMIE_INSTALL_URL` only when you want to override the public GitHub raw location, for example with an enterprise Artifactory mirror. If it is unset, `install/windows/install.cmd` downloads the PowerShell installer from this public repository. `CODEMIE_INSTALL_URL` points at the **directory** containing `install.ps1`, not the file itself. - -Channel selection is not implemented in the bootstrap scripts yet. Install the default npm package version, or pass an explicit version with PowerShell `-Version` or shell `CODEMIE_PACKAGE_VERSION`. - -## GitHub Raw URLs - -Use `main` for the latest installer source. - -Windows PowerShell: - -```powershell -irm https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.ps1 | iex -``` - -Windows CMD: - -```cmd -curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.cmd -o install.cmd && install.cmd && del install.cmd -``` - -macOS, Linux, and WSL: - -```bash -curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | bash -``` - -Direct file URLs: - -```text -https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.ps1 -https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows/install.cmd -https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh -``` - -For reproducible installs, replace `main` with a release tag such as `v0.8.0`. - -## Script Options - -### Windows PowerShell (`install/windows/install.ps1`) - -| Parameter | Default | Values / Purpose | -|---|---|---| -| `-Mode` | `portable` | `portable` = npm prefix under `-InstallRoot` with shim `.cmd` files in `bin/` and a user PATH update; `npm-global` = plain `npm install -g` into the existing npm prefix | -| `-Version` | *(empty)* | Pin `@codemieai/code` to a specific version | -| `-RegistryUrl` | `https://registry.npmjs.org/` | npm registry used for resolution and install | -| `-ScopeRegistryUrl` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | -| `-InstallRoot` | `%LOCALAPPDATA%\CodeMie` | Portable install root (`-Mode portable` only) | -| `-DryRun` | *(switch)* | Print every action without executing it | - -### macOS / Linux / WSL (`install/macos/install.sh`) - -| Env var | Default | Values / Purpose | -|---|---|---| -| `CODEMIE_INSTALL_MODE` | `auto` | `auto` = `npm-global` if the npm prefix is user-writable, otherwise `user-prefix`; `npm-global` = plain global install; `user-prefix` = install under `CODEMIE_NPM_PREFIX` | -| `CODEMIE_NPM_PREFIX` | `$HOME/.codemie/npm-prefix` | npm prefix used when `INSTALL_MODE` resolves to `user-prefix` | -| `CODEMIE_PACKAGE_VERSION` | *(empty)* | Pin `@codemieai/code` to a specific version | -| `CODEMIE_REGISTRY_URL` | `https://registry.npmjs.org/` | npm registry used for resolution and install | -| `CODEMIE_SCOPE_REGISTRY_URL` | *(empty)* | Sets the `@codemieai:registry` npm scope to an enterprise registry | - -Pin a version on macOS/Linux/WSL: - -```bash -curl -fsSL https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/macos/install.sh | env CODEMIE_PACKAGE_VERSION=0.8.0 bash -``` - -## Windows Defaults - -Windows installs into the current user's local profile by default (`-Mode portable`): - -```text -%LOCALAPPDATA%\CodeMie -``` - -The installer calls `npm.cmd` directly to avoid PowerShell resolving `npm` to `npm.ps1`. - -Known limitation: `install/windows/install.cmd` forwards arguments to PowerShell through `%*`. Use the PowerShell installer directly when passing arguments that contain spaces, such as `-InstallRoot "C:\My Folder"`. - -## macOS/Linux Defaults - -macOS, Linux, and WSL use `CODEMIE_INSTALL_MODE=auto` by default: npm global installation when global npm is user-writable. If global npm is not writable, the script configures a user-local npm prefix (`$HOME/.codemie/npm-prefix`). - -## Windows Installation Wizard - -`install/windows/CodeMie Connect_2.0.1_x64-setup.exe` is a self-contained Windows desktop GUI application that installs and configures the CodeMie Claude Code CLI end-to-end. It requires no terminal knowledge and bundles all dependencies. - -### Running the Wizard - -Double-click `CodeMie Connect_2.0.1_x64-setup.exe`. No command-line arguments are supported — the wizard is a pure GUI application. - -The wizard walks through the following steps in order: - -| Step | What it does | -|------|-------------| -| PowerShell execution policy | Sets `RemoteSigned` scope for the current user | -| Git for Windows | Detects an existing install or silently downloads and installs v2.47.0-64-bit | -| Node.js + npm | Detects an existing install or silently downloads and installs Node.js LTS v20.18.0 | -| CodeMie CLI | Installs `@codemieai/code` globally via `npm install -g` | -| CodeMie setup | Opens a visible terminal window and runs `codemie setup` interactively | -| Claude engine | Opens a visible terminal window and runs `codemie install claude --supported` | -| Validation | Runs `codemie doctor` to confirm everything is working | - -Each step that requires a download shows a progress animation and an inline **Approve** / **Ignore** button before proceeding. - -### Unattended Mode - -Check the **Unattended mode** checkbox in the left sidebar before clicking Install. All approval gates auto-approve, so the wizard runs without prompts. The two interactive terminal steps (`codemie setup` and `codemie install claude`) still open a visible console window because they require user input. - -### Default Paths - -Tools are installed to their standard system locations: - -```text -Git: C:\Program Files\Git\cmd\git.exe -Node: C:\Program Files\nodejs\node.exe -``` - -npm global binaries are added to the current user's `PATH`: - -```text -%USERPROFILE%\AppData\Local\CodeMie\npm-prefix -%USERPROFILE%\AppData\Roaming\npm -``` - -### Log File - -All wizard output is written to: - -```text -%TEMP%\codemie_wizard.log -``` - -The log persists across runs. Each line is prefixed with an ISO-8601 timestamp and a tag: `[OUT]` stdout, `[ERR]` stderr, `[INF]` info, `[OK]` success, `[CMD]` command. - -## macOS Installation Wizard - -`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` is a signed macOS desktop GUI application for **Apple Silicon (aarch64)** Macs. It installs and configures the CodeMie CLI and Claude engine end-to-end with no terminal required. (An Intel x86_64 build is not shipped.) - -The wizard is built from a separate repository (`codemie-claude-installer-mac`); the `.dmg` committed here is the distributed artifact. - -### Running the Wizard - -Download `CodeMie Connect_2.0.1_aarch64_signed.dmg` from the [macOS install folder](https://github.com/codemie-ai/codemie-code/tree/main/install/macos), open it, and run the app. The wizard walks the user through installing prerequisites (Xcode Command Line Tools, Node.js, Git), the CodeMie CLI, an interactive `codemie setup`, the Claude engine via `codemie install claude`, and a final `codemie doctor` validation. - -### Log File - -Wizard output is written to: - -```text -~/Library/Logs/CodeMie/ -``` - -The log persists across runs. - -> The wizard version (`2.0.1` in the filename) is independent of the `@codemieai/code` npm package version. - -## Release Artifacts - -Run this command to prepare publishable artifacts: - -```bash -npm run prepare:install-artifacts -``` - -Generated files are written to `artifacts/install/` and are not committed. - -Generated artifacts include a version header and their checksums are computed from the generated artifact content, not from the source files under `install/`. -```` - -- [ ] **Step 2: Verify all script params/env-vars are documented** - -Run these greps — each must return at least one match in `install/README.md`: - -```bash -grep -c 'Mode' install/README.md # PowerShell -Mode -grep -c 'DryRun' install/README.md # PowerShell -DryRun -grep -c 'INSTALL_MODE' install/README.md # shell CODEMIE_INSTALL_MODE -grep -c 'NPM_PREFIX' install/README.md # shell CODEMIE_NPM_PREFIX -grep -c 'aarch64' install/README.md # macOS dmg -grep -c 'v0.8.0' install/README.md # refreshed tag -grep -c 'Library/Logs/CodeMie' install/README.md # macOS log path -``` - -Expected: every count `>= 1`. Also confirm the stale tag is gone: - -```bash -grep -c 'v0.0.57' install/README.md # must be 0 -``` - -- [ ] **Step 3: Commit** - -```bash -git add install/README.md -git commit -m "docs(install): document macOS dmg installer and script options in README" -``` - ---- - -## Self-Review - -**Spec coverage (drift items from technical-analysis.md):** -- Drift 1 (macOS dmg undocumented) → Task 1: new "macOS Installation Wizard" section + intro/distribution list entries. ✅ -- Drift 2 (PowerShell params) → Task 1: "Script Options → Windows PowerShell" table, all 6 params. ✅ -- Drift 3 (shell env vars) → Task 1: "Script Options → macOS/Linux/WSL" table, all 5 vars. ✅ -- Drift 4 (stale tag) → Task 1: `v0.0.57` → `v0.8.0`. ✅ -- Drift 5 (mode asymmetry) → Task 1: modes named (`portable`, `auto`/`npm-global`/`user-prefix`) in Defaults + Script Options. ✅ -- Drift 6 (CMD wrapper) → Task 1: clarified `CODEMIE_INSTALL_URL` points at the directory. ✅ - -**Placeholder scan:** none. Full target file content is inline. - -**Type/name consistency:** filenames and URLs match the actual folder contents (`CodeMie Connect_2.0.1_aarch64_signed.dmg`, `install/macos/install.sh`, etc.). diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md deleted file mode 100644 index 9fbe4dcc..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/qa-report.md +++ /dev/null @@ -1,32 +0,0 @@ -# QA Gate Report — update-install-readme - -**Branch**: docs/install-readme-update -**Runner**: npm -**Started**: 2026-07-03T14:10:00Z -**Status**: PASSED - -## Changed files (vs merge_base da7d0df) -- `install/README.md` (docs-only; Markdown) - -## Gates - -| Gate | Status | Duration | Command | Notes | -|------|--------|----------|---------|-------| -| license-check | N/A | — | `npm run license-check` | scans `src/` Apache headers; no `src/` file touched | -| lint | PASS | ~8s | `npm run lint` | exit 0, zero warnings; scope `{src,tests}/**/*.ts` (no .ts touched, whole-project clean) | -| typecheck | PASS | ~3s | `npm run typecheck` | exit 0, no diagnostics | -| build | SKIPPED | — | `npm run build` | guide Skip-if: "pure docs" edits — change is a single `.md` | -| unit | SKIPPED | — | `npm run test:unit` | guide Skip-if: doc-only change | -| integration | SKIPPED | — | `npm run test:integration` | no integration coverage of a README; doc-only | -| secrets | PASS | — | `npm run validate:secrets` | ran via pre-commit hook on both commits; no leaks | -| commitlint | PASS | — | `npm run commitlint:last` | enforced by commit-msg hook on both commits; scope `cli` valid | -| ui | SKIPPED | — | (n/a) | no UI surface changed (`.md` only) | - -## Failure detail (if any) -None. - -## Drift signal -no — implementation matches plan; code review (final + check) passed. - -## Outcome -PASSED. All in-scope gates green; doc-only skip-eligible gates skipped per `.ai-run/guides/quality-gates.md`. diff --git a/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md b/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md deleted file mode 100644 index 50de3344..00000000 --- a/docs/superpowers/tasks/2026-07-03-update-install-readme/technical-analysis.md +++ /dev/null @@ -1,75 +0,0 @@ -# Technical Analysis — update-install-readme - -## Task -Update `install/README.md` so it accurately reflects the actual contents of the `install/` folder. The README is out of date. - -## Scope -Docs-only change. Single file: `install/README.md`. No code, no scripts, no behavior change. - -## Codebase Findings - -### Folder contents (ground truth) -`install/` contains exactly six entries: - -| Path | Type | Documented in README? | -|---|---|---| -| `README.md` | doc | (self) | -| `macos/install.sh` | shell bootstrap script | ✅ partially | -| `macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` | macOS GUI installer (signed, Apple Silicon) | ❌ **missing entirely** | -| `windows/install.ps1` | PowerShell bootstrap script | ✅ partially | -| `windows/install.cmd` | CMD wrapper | ✅ | -| `windows/CodeMie Connect_2.0.1_x64-setup.exe` | Windows GUI wizard | ✅ detailed | - -### Drift item 1 — macOS `.dmg` installer undocumented (major) -`install/macos/CodeMie Connect_2.0.1_aarch64_signed.dmg` (2.6 MB, signed, aarch64/Apple Silicon) has **zero coverage** in `install/README.md`. The top-level `README.md:71` documents it as a GUI installer option, but `install/README.md`'s only "Installation Wizard" section covers Windows exclusively. -- The macOS wizard is a SwiftUI app built in a **separate repository** (`codemie-claude-installer-mac`; per `docs/superpowers/plans/2026-06-03-codemie-claude-installer-mac.md`). Its step list / log path are not verifiable from this repo. -- Verifiable facts: filename, signed, aarch64 (Apple Silicon) only, GUI/no-terminal, download/browse URLs. - -### Drift item 2 — PowerShell `install.ps1` parameters underdocumented -The README mentions only `-Version` and `-InstallRoot`. Actual parameters (`install.ps1:2-9`): - -| Param | Values / default | Purpose | -|---|---|---| -| `-Mode` | `portable` (default) \| `npm-global` | portable = npm prefix under InstallRoot + shim `.cmd`s in `bin/`; npm-global = plain `npm install -g` | -| `-Version` | string, default `''` | pin package version | -| `-RegistryUrl` | default `https://registry.npmjs.org/` | npm registry | -| `-ScopeRegistryUrl` | default `''` | sets `@codemieai:registry` | -| `-InstallRoot` | default `%LOCALAPPDATA%\CodeMie` | portable install root | -| `-DryRun` | switch | print actions, execute nothing | - -### Drift item 3 — Shell `install.sh` env vars underdocumented -README mentions only `CODEMIE_PACKAGE_VERSION` (and `CODEMIE_INSTALL_URL` for the CMD wrapper). Actual env vars (`install.sh:6-10`): - -| Env var | Values / default | Purpose | -|---|---|---| -| `CODEMIE_REGISTRY_URL` | default `https://registry.npmjs.org/` | npm registry | -| `CODEMIE_SCOPE_REGISTRY_URL` | default `''` | sets `@codemieai:registry` | -| `CODEMIE_INSTALL_MODE` | `auto` (default) \| `npm-global` \| `user-prefix` | auto picks npm-global if prefix writable, else user-prefix | -| `CODEMIE_NPM_PREFIX` | default `$HOME/.codemie/npm-prefix` | user-prefix target | -| `CODEMIE_PACKAGE_VERSION` | default `''` | pin package version | - -### Drift item 4 — stale version example -README pins the example release tag to `v0.0.57` (lines 51, 86 equivalent). `package.json` version is now `0.8.0`. Example tag should be refreshed to `v0.8.0`. (The top-level `README.md` carries the same stale `v0.0.57` examples, but that file is out of scope here.) - -### Drift item 5 — install-mode asymmetry unexplained -Windows default = `portable` mode (npm prefix + 7 shim `.cmd` files under `bin/`, PATH update). macOS/Linux default = `auto` (npm-global if writable, else user-prefix with `$HOME/.codemie/npm-prefix`). README describes both behaviors but never names the modes or maps them to the script params/env vars, so the two columns read as inconsistent rather than symmetric. - -### Drift item 6 — CMD wrapper behavior -`install/windows/install.cmd` (verified): defaults `CODEMIE_INSTALL_URL` to `https://raw.githubusercontent.com/codemie-ai/codemie-code/main/install/windows`, `curl`s `install.ps1` to `%TEMP%`, executes it, deletes it. README's CMD section is accurate but light on the `CODEMIE_INSTALL_URL` override semantics (it overrides the **directory**, not the file). - -### Accurate content to preserve -- GitHub raw URL section (lines 21–51) — correct, just needs tag refresh. -- Windows Defaults section (`%LOCALAPPDATA%\CodeMie`, `npm.cmd` direct call, `%*` forwarding limitation) — accurate. -- macOS/Linux Defaults paragraph — accurate. -- Windows Installation Wizard section (steps table, unattended mode, default paths, log file) — authoritative; preserve as-is. -- Release Artifacts section — accurate (`npm run prepare:install-artifacts` → `artifacts/install/`, checksums from generated content). - -## Risk Indicators -- **Binary `.dmg`/`.exe` in repo** — README must not claim behaviors verifiable only from the (separate-repo) wizard sources. Keep macOS wizard section factual. -- **Version-pinned filenames** (`CodeMie Connect_2.0.1_*`) drift from npm package version (`0.8.0`) — different versioning schemes; README should state the wizard version as part of the filename, not imply it equals the npm version. -- **`artifacts/install/manifest.json`** still shows `packageVersion: 0.0.57` — generated artifact, out of scope for this README fix; do not "fix" it. - -## Orchestrator Digest -Single-file docs update with clear, codebase-grounded drift list. No ambiguity in *what* to fix; the only judgment call is how much detail to give the macOS wizard given its sources live in another repo — recommendation is a factual minimal section (existence, platform, signed, download/browse link) mirroring the top-level README's treatment, not a fabricated step table. No code, no tests, no scripts touched. - -**Open questions:** none blocking — proceeding with the minimal-but-factual macOS wizard section and a consolidated script-options reference table.