@poetic-ai/poetic 1.42.0

package/INSTALL.md

@@ -0,0 +1,454 @@
+# Poetic Installation Guide
+
+Poetic is MIT-licensed open-source software distributed through the public npm
+package `@poetic-ai/poetic`. The Software may be used, copied, modified,
+published, distributed, sublicensed, and sold under the terms of the
+[MIT License](./LICENSE).
+
+After install, run `poetic provider setup --first-run`, then `cd` into the git
+repository you want Poetic to work on and run `poetic init` then `poetic doctor`.
+`poetic init quickstart` is an optional branch helper. Agents
+and scripts can read compact machine context with `poetic context --json`.
+
+> **Pin automation.** The floating npm and repository commands are convenient
+> for interactive installs. Reproducible automation should pin both the script
+> ref and package version (for example `v1.42.0` / `1.42.0`).
+
+## Choose your path
+
+The npm package and official repository installer are both supported. The
+source repository remains private until the open-source switch; authenticated
+users can fetch the same installer through `gh api` in the meantime.
+
+| You are...                                    | Use this                                                                     | Then                                                                                              |
+| --------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| An end user                                  | `npm install -g @poetic-ai/poetic` or the official `install.sh` | `poetic provider setup --first-run`, then `cd <target-git-repo>` and `poetic init` then `poetic doctor` |
+| An end user without a writable global prefix | Configure a user-owned npm prefix, then use npm or the installer | `poetic provider setup --first-run`, then `cd <target-git-repo>` and `poetic init` then `poetic doctor` |
+| An agent or CI job                           | Run the pinned installer with `--strict --skip-setup --skip-doctor --no-modify-path` | `poetic context --json` or `poetic provider list --json`                            |
+| Advanced recovery / package-manager only     | Pin and install the public package directly (see Advanced package install) | `poetic provider setup --first-run`, then `poetic init` then `poetic doctor`                          |
+| A contributor                                | Clone the repository with authenticated `gh`, run `npm install`, then `./scripts/build-poetic.sh` | Run validation from a target git repository                                         |
+
+Run `poetic init` in the target repository for the full project scaffold, then
+`poetic doctor`. Most other commands can auto-create a **minimal** runtime
+`.poetic/` on first use; that is not a substitute for `poetic init`.
+`poetic init quickstart` remains an optional readiness and branch helper.
+
+## Prerequisites
+
+- Node.js 24.x — other majors are not validated against Poetic's native deps yet
+- npm 9+ (bundled with Node)
+- A user-owned npm prefix (do not use sudo)
+- macOS or Linux (Windows: use WSL). WSL is treated as a Linux desktop. Install
+  and read-only CLI commands work on Linux without host-class consent.
+  Write-capable provider automation on macOS still requires Seatbelt or an
+  attested container. On Linux, isolated hosts (VM/container/cloud/CI) just
+  work; desktops warn and require `poetic sandbox trust linux --ack-desktop` or
+  a TTY prompt — never a platform ban. Cloud images can set
+  `POETIC_SANDBOX_LINUX_HOST_CLASS=isolated`. Details:
+  [docs/reference/SECURITY.md](./docs/reference/SECURITY.md#runtime-security-boundaries).
+- Git — required for normal operation (isolated worktrees and project workflows),
+  as well as for source builds and `install.sh --source git`
+
+### Existing Checkouts and Other Machines
+
+Every machine that runs Poetic from this repository must resolve `node` to
+24.x from the shell that runs Poetic. After switching an existing checkout from
+an older Node major, reinstall dependencies under Node 24 so native modules
+such as `better-sqlite3` are rebuilt for the active runtime:
+
+```bash
+node --version  # must print v24.x
+npm ci
+```
+
+With `nvm`, use the repository pin:
+
+```bash
+nvm install 24
+nvm use
+npm ci
+```
+
+With Homebrew Node on macOS, put Node 24 first on `PATH` before installing or
+testing:
+
+```bash
+brew install node@24
+export PATH="/opt/homebrew/opt/node@24/bin:$PATH"
+node --version
+npm ci
+```
+
+## Quick Install
+
+Install directly from npm:
+
+```bash
+npm install -g @poetic-ai/poetic
+```
+
+After the repository becomes public, the floating one-line installer is:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ebrindley/Poetic/main/install.sh | bash
+```
+
+After that public-source switch, pin both inputs for reproducible automation.
+`--strict` makes post-install identity and health warnings fail the install:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ebrindley/Poetic/v1.42.0/install.sh \
+  | bash -s -- --version 1.42.0 --strict
+```
+
+While the repository is private, authenticated users can execute the exact same
+tagged installer bytes:
+
+```bash
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --version 1.42.0 --strict
+```
+
+The installer's default source is `auto`, which installs from the public npm
+package channel.
+If the npm package cannot be resolved (registry outage, unpublished version),
+the installer fails loudly with guidance — there is no silent fallback to a
+git ref, because `npm install -g git+...` against an unbuilt ref does not
+produce a working CLI. To install from a git ref intentionally, pass
+`--source git --version <ref>`; the ref must contain a built `dist/` tree.
+
+1. Verify Node 24.x, npm, platform support, and writable npm prefix.
+2. Resolve `@poetic-ai/poetic@<pinned-version>` to a concrete npm version.
+3. Skip install if `~/.poetic/install.json` already records that version.
+4. Install the concrete version resolved in step 2 (never a floating tag as the supported story).
+5. On failure, attempt a best-effort rollback to the previous manifest target.
+6. Optionally update PATH in your shell rc.
+7. Verify selected-prefix identity with `poetic debug version --json`, then run
+   `poetic doctor --json` and surface failures and warnings.
+8. Hand off to guided provider setup via `poetic provider setup --first-run`.
+9. Run `poetic init quickstart` from the target git repository you want Poetic to change.
+
+## Exact npm package install
+
+Pin npm itself for reproducible CI or rollback:
+
+```bash
+npm install -g @poetic-ai/poetic@1.42.0
+```
+
+The floating command resolves `@poetic-ai/poetic@latest`; the exact command
+always resolves `1.42.0`.
+
+After a direct package install, run setup and quickstart yourself:
+
+```bash
+poetic provider setup --first-run
+cd <target-git-repo>
+poetic init quickstart
+```
+
+## Contributor / Git Source
+
+Use the git source for unreleased refs only when the ref already contains a
+built `dist/` tree:
+
+```bash
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --source git --version <ref-with-built-dist>
+```
+
+Contributors validating unreleased code should build from a clone:
+
+```bash
+gh auth login
+gh repo clone ebrindley/Poetic
+cd Poetic
+nvm use
+npm install
+./scripts/build-poetic.sh
+poetic --version
+```
+
+`./scripts/build-poetic.sh` is the canonical source-build path: it rebuilds the
+CLI and wires the local `poetic` command for contributor validation.
+
+For the advanced git-source installer, `GITHUB_TOKEN` is passed through an
+ephemeral `GIT_ASKPASS` helper under the installer temp directory. It is not
+written to `~/.git-credentials` or global git config.
+
+> Note on `gh auth login`: when `gh` is detected and authenticated, the
+> installer can configure `credential.https://github.com.helper` in your
+> _global_ git config to use `!gh auth git-credential` so authenticated git
+> operations work without prompts. Interactive installs ask first. Non-
+> interactive installs skip this global git config write unless
+> `POETIC_MODIFY_GIT_CREDENTIALS=1` is set. Existing helpers for github.com are
+> preserved. The installer appends the `gh` helper only when it is absent,
+> verifies the exact resulting list, and restores the prior list if configuration
+> fails.
+
+## Flags and Environment Variables
+
+Flags go after `--` when piping through bash. Flags take precedence over env.
+
+| Flag                  | Env var                   | Default                              | Purpose                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--source <source>`   | `POETIC_INSTALL_SOURCE`   | `auto`                               | `auto`, `package`/`stable`, or `git`                                                                                                                                                                                                                  |
+| `--version <ref>`     | `POETIC_VERSION`          | `latest` for package, `main` for git | npm version/dist-tag or git ref                                                                                                                                                                                                                       |
+| `--package <name>`    | `POETIC_PACKAGE`          | `@poetic-ai/poetic`                        | npm package name                                                                                                                                                                                                                                      |
+| `--force`             | `POETIC_FORCE=1`          | off                                  | reinstall even if manifest matches                                                                                                                                                                                                                    |
+| `--dry-run`           | `POETIC_DRY_RUN=1`        | off                                  | print plan, make no changes                                                                                                                                                                                                                           |
+| `--install-dir <dir>` | `POETIC_INSTALL_DIR`      | npm prefix                           | override install location                                                                                                                                                                                                                             |
+| `--no-modify-path`    | `POETIC_NO_MODIFY_PATH=1` | off                                  | never write to shell rc                                                                                                                                                                                                                               |
+| `--modify-path`       | `POETIC_MODIFY_PATH=1`    | off                                  | force shell-rc edit even when non-interactive                                                                                                                                                                                                         |
+| `--skip-setup`        | `POETIC_SKIP_SETUP=1`     | off                                  | skip first-run wizard hand-off                                                                                                                                                                                                                        |
+| `--skip-doctor`       | `POETIC_SKIP_DOCTOR=1`    | off                                  | skip post-install `poetic doctor`                                                                                                                                                                                                                     |
+| `--strict`            | `POETIC_INSTALL_STRICT=1` | off                                  | fail install when prefix identity integrity fails, when `poetic doctor --strict` exits non-zero, or when a non-interactive `poetic provider list` reports no ready provider. Without `--strict`, health warnings and an unconfigured-provider state are logged but do not fail the install. |
+| `--yes` / `-y`        | `POETIC_YES=1`            | off                                  | select non-interactive mode; it does not opt into PATH, credential-helper, or provider-install mutations                                                                                                                                               |
+|                       | `POETIC_MODIFY_GIT_CREDENTIALS=1` | off                         | allow non-interactive installs to configure the global GitHub credential helper when authenticated `gh` is available                                                                                                                                  |
+
+`--strict` plus doctor requires a ready provider; `--skip-doctor` keeps prefix-integrity-only.
+
+Other recognized env vars: `GITHUB_TOKEN`, `NO_COLOR`, `CI`,
+`DEBIAN_FRONTEND`, `POETIC_ALLOW_UNSUPPORTED_NODE`.
+
+## Examples
+
+```bash
+# Authenticated exact installer while the repository is private
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --version 1.42.0 --strict
+
+# Exact package-manager install
+npm install -g @poetic-ai/poetic@1.42.0
+
+# Advanced: install a ref that already contains a built dist/ tree
+curl -fsSL .../install.sh | bash -s -- --source git --version <ref-with-built-dist>
+
+# Reinstall current target
+curl -fsSL .../install.sh | bash -s -- --force --version 1.42.0
+
+# Preview without changes
+curl -fsSL .../install.sh | bash -s -- --dry-run --version 1.42.0
+
+# CI / non-interactive prefix-integrity only (no ready-provider gate)
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | CI=true bash -s -- --version 1.42.0 --skip-setup --skip-doctor --no-modify-path --strict
+```
+
+## Updating Poetic
+
+Use the first-class upgrade command:
+
+```bash
+poetic upgrade --check
+poetic upgrade
+poetic upgrade --version 1.42.0
+poetic upgrade --refresh-integrations
+```
+
+If you installed from a source checkout, update the checkout and
+rebuild the linked CLI instead:
+
+```bash
+git pull --ff-only
+nvm use
+npm install
+./scripts/build-poetic.sh
+```
+
+Re-running the installer is also supported and remains idempotent. Pin the
+script ref the same way as first install:
+
+```bash
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --version 1.42.0
+```
+
+`poetic upgrade` and `install.sh` share the same `~/.poetic/install.json`
+manifest but cover different scopes. Use the table below to pick:
+
+| Capability                                         | `install.sh` | `poetic upgrade`                |
+| -------------------------------------------------- | ------------ | ------------------------------- |
+| First-time install                                 | yes          | no (CLI is not on PATH yet)     |
+| Source `auto` (stable npm channel)                 | yes          | no — pass `--source` explicitly |
+| PATH / shell rc edits                              | yes          | no                              |
+| Post-install `poetic doctor` + guided setup handoff | yes          | no                              |
+| Audit installed cleanup integrations             | no           | yes                             |
+| Refresh installed cleanup integrations           | no           | opt-in with `--refresh-integrations` |
+| Manifest read for skip/idempotency                 | yes          | yes                             |
+| Best-effort rollback on failure                    | yes          | yes                             |
+| Channel-switch refusal without `--force`           | n/a          | yes                             |
+
+## Idempotency and Rollback
+
+A successful stable-channel install writes `~/.poetic/install.json`:
+
+```json
+{
+  "schema": 2,
+  "source": "package",
+  "ref": "latest",
+  "package": "@poetic-ai/poetic",
+  "version": "1.42.0",
+  "prefix": "/opt/homebrew",
+  "installedAt": "2026-05-16T18:00:00.000Z"
+}
+```
+
+Git-source installs record `source: "git"` and the resolved commit instead of
+the npm version. On re-run, the installer compares the manifest against the
+resolved target and skips `npm install` unless `--force` is passed.
+
+Rollback is best-effort, not atomic: on `npm install` failure the installer
+attempts to reinstall the previous manifest target. If rollback fails, the
+previous manifest is preserved at `~/.poetic/install.json.bak`.
+
+If `npm install` succeeds but post-install verification fails (`poetic doctor`,
+`poetic provider list`, or `--strict` gating), the package remains installed
+unless selected-prefix identity integrity failed (that path is still part of
+the install mutation and triggers best-effort package/PATH rollback). The
+installer logs readiness warnings unless `--strict` is set; fix configuration
+and re-run `poetic doctor` or `poetic init quickstart` without reinstalling.
+
+## Verifying the Install
+
+```bash
+poetic --version
+poetic debug version --json
+poetic init quickstart
+poetic doctor
+poetic doctor --json
+poetic provider list
+```
+
+`poetic debug version --json` is the install identity check (at least a
+non-empty `packageVersion`; `installType` is also useful when present). The
+official installer uses that probe for post-mutation prefix integrity under
+the supported `--strict` path.
+
+For the first-user path, `poetic provider list` should report at
+least one ready provider before you run your first task (`poetic run` for
+straightforward single-provider work, or `poetic compete` when you want judge
+scores or multi-variant comparison). If Grok is your first provider, install
+through Poetic's guarded setup path with
+`POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers grok`, then run `grok` once
+for browser auth or set `XAI_API_KEY` for headless shells.
+
+## Uninstalling
+
+```bash
+npm uninstall -g @poetic-ai/poetic
+rm -rf ~/.poetic    # optional, removes manifest and project state
+```
+
+To remove the shell-rc PATH block, delete the lines between
+`# >>> poetic >>>` and `# <<< poetic <<<` in your shell rc.
+
+## Troubleshooting
+
+### `Command not found: poetic`
+
+The npm global bin is not on PATH. Re-run the installer interactively so it
+can offer to update your shell rc, or add it manually:
+
+```bash
+echo 'export PATH="'"$(npm config get prefix)"'/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### `poetic` runs the wrong tool
+
+An unrelated npm package named `poetic` (a linter/formatter installer, last
+published 2021) also claims the `poetic` binary. If both are installed
+globally, whichever was installed last owns the command. Check with
+`poetic --version` (this package reports a Poetic CLI version) and remove the
+other tool with `npm uninstall -g poetic` if you do not use it.
+
+### `Permission denied` during `npm install`
+
+Do not use sudo. Reconfigure npm to a user-owned prefix:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+Or pass `--install-dir <dir>` to the installer.
+
+### `@poetic-ai/poetic@latest` Cannot Be Resolved
+
+The npm registry is unreachable or the requested version has not been
+published. The installer never silently falls back to a git ref —
+`npm install -g
+git+...` against an unbuilt ref produces a broken `poetic` shim, so the only
+safe paths are:
+
+1. Retry once the registry recovers or the requested version is published.
+2. Pin a published version: `--version <semver>`.
+3. Build from the authenticated source repository while it is private:
+
+   ```bash
+   gh auth login
+   gh repo clone ebrindley/Poetic
+   cd Poetic
+   nvm use
+   npm install
+   ./scripts/build-poetic.sh
+   ```
+
+4. As an explicit advanced opt-in, install from a git ref that already
+   contains a built `dist/` tree:
+
+   ```bash
+   gh api -H 'Accept: application/vnd.github.raw+json' \
+     'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+     | bash -s -- --source git --version <ref-with-built-dist>
+   ```
+
+### Git Auth Failure
+
+Only git-source installs need GitHub credentials. Re-run after one of:
+
+```bash
+gh auth login
+# or:
+export GITHUB_TOKEN=ghp_xxx
+```
+
+### `better-sqlite3` Build Error
+
+```bash
+npm rebuild better-sqlite3
+# or reinstall via the pinned official installer, or as advanced recovery:
+npm uninstall -g @poetic-ai/poetic
+npm install -g @poetic-ai/poetic@1.42.0 --force
+```
+
+## Release Verification
+
+Release automation validates the package before and after candidate publishing:
+
+- `npm run verify:dist` (built artifact + `package.json#files` contract)
+- `npm run test:installer`
+- `npm run release:pack-smoke` (tarball manifest + temp-prefix install smoke)
+- `npm run release:artifacts`
+- `npm publish <tarball> --access public --tag next` through npm trusted publishing
+- exact-version registry install and CLI identity canary
+- draft GitHub release with the npm tarball, `SHA256SUMS`, release manifest,
+  and generated Homebrew formula
+
+At a release checkpoint, tag the reviewed merge commit. The workflow publishes
+that immutable version to `next`, verifies it, and creates a draft GitHub
+release. After clean-environment dogfood passes, an npm org owner promotes the
+same version with `npm dist-tag add @poetic-ai/poetic@1.42.0 latest`, then
+publishes the draft GitHub release. Ordinary commits do not update installers.
+The first package creation is a one-time local, 2FA-authenticated bootstrap;
+subsequent releases use the trusted-publisher entry for this repository and
+workflow. Provenance can be re-enabled after the source repository is public.
+For local release and operator checks, see [scripts/OPERATOR.md](https://github.com/ebrindley/Poetic/blob/main/scripts/OPERATOR.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ed Brindley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.