@zoahhq/cli 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zoah Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,348 @@
+<p align="center">
+  <img src="https://zoah.com/assets/images/opacity-mark.svg" alt="Zoah" width="84" />
+</p>
+
+# @zoahhq/cli
+
+The Zoah CLI. Sign in from your terminal, import first-party React components into Zoah, and optionally rewrite local imports.
+
+Published to npm as [`@zoahhq/cli`](https://www.npmjs.com/package/@zoahhq/cli). The package installs the `zoah` command.
+
+## Install
+
+```bash
+npm install -g @zoahhq/cli
+```
+
+Verify the installation with `zoah --version`. The package also provides `opacity` as a temporary compatibility alias.
+
+## Quick start
+
+```bash
+zoah login          # sign in via your browser
+zoah import         # scan ./src, import and publish your components
+zoah import --swap  # also rewrite local imports to the published package
+```
+
+## Commands
+
+### `zoah login`
+
+Opens your browser to the Zoah sign-in flow. It saves the credential with `chmod 600`. Other commands reuse its token and base URL.
+
+Credentials are layered (same precedence as `git config local > global`):
+
+- **Default, global:** writes `~/.zoah/credentials.json`. One sign-in covers every Zoah project on this machine.
+- **`--local`:** writes `<cwd>/.zoah/credentials.json`. Use this for a project-specific account or instance. The CLI also writes `<cwd>/.zoah/.gitignore`.
+
+Reads always check local first; falls back to global.
+
+```bash
+zoah login                                      # global default
+zoah login --local                              # project-specific override
+zoah login --base-url https://zoah.example.com
+```
+
+The CLI uses `ZOAH_BASE_URL` when it is set. Otherwise, it uses `https://zoah.com`. `OPACITY_BASE_URL` remains a compatibility fallback.
+
+### `zoah logout`
+
+By default, this removes the **active** credentials. It removes project-local credentials when they exist, and otherwise removes global credentials.
+
+- `zoah logout`: clear the active layer only.
+- `zoah logout --global`: remove `~/.zoah/credentials.json` even when a project-local override is also present.
+
+To clear both, run logout twice.
+
+### `zoah whoami`
+
+Prints the active user, the source credentials file, and the base URL. Use this when project credentials hide the global token.
+
+```bash
+zoah whoami
+# Signed in as you@example.com (global).
+#   Source:   ~/.zoah/credentials.json
+#   Base URL: https://zoah.com
+```
+
+### `zoah mcp`
+
+Serves the Zoah Action API over MCP (stdio) so a coding agent (Claude Code,
+Codex, Cursor, or any MCP-capable harness) can read and edit a Zoah project
+from your terminal session. The agent gets the same verbs the designer uses:
+nodes, pages, components, slots, variants, variables, themes, breakpoints and
+events, plus branch and pull-request tools.
+
+#### Set it up
+
+**1. Sign in once.** The MCP server reuses the credential `zoah login`
+writes. It never asks the agent for one.
+
+```bash
+npm i -g @zoahhq/cli
+zoah login
+```
+
+**2. Add the server to your harness.** The guided installer is the fast path:
+
+```bash
+zoah mcp init
+```
+
+It asks four things:
+
+| Question           | Options                                                     | Pick this when                                                |
+| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------- |
+| Which harness      | Claude Code, Cursor, VS Code, Codex, or print the snippet   | Pick the harness that will use Zoah                           |
+| How to launch      | `npx -y @zoahhq/cli@latest`, or the global `zoah` binary    | `npx` for a config you check in, so teammates need no install |
+| What agents may do | full access, or `--read-only`                               | read-only serves the query verbs alone                        |
+| Default project    | the repo's linked project from `.zoah/config.json`, or none | baking it in means `connect` needs no ids                     |
+
+It merges into an existing config without disturbing other servers. Every answer
+is also a flag (`--harness`, `--global-command`, `--read-only`, `--project`,
+`--print`) for scripted setup.
+
+To write the entry by hand instead:
+
+```json
+{
+  "mcpServers": {
+    "zoah": {
+      "command": "npx",
+      "args": ["-y", "@zoahhq/cli@latest", "mcp"]
+    }
+  }
+}
+```
+
+**3. Point the agent at a project.** In the agent session:
+
+```
+connect(project: "my-project")
+```
+
+`connect` signs in when the credential is missing or expired. It returns a URL
+for you to approve in a browser, then resolves the project by slug, name or id
+and opens the session. Give it `branch` to pick one. With no branch it creates a
+fresh `agent/<timestamp>` branch off main, so an agent's edits stay reviewable
+rather than landing on main.
+
+**4. Check it worked.** `status` reports the connected project, the branch, and
+workspace role. It also reports credential health. `whoami` reports the
+identity, role, and instance.
+
+#### What the agent gets
+
+The server exposes each Action API verb that can run in a headless project
+session without direct human confirmation. Confirmation actions stay in the
+Zoah app. The server replaces renderer-only and workspace-agent verbs with
+the session tools below.
+
+| Group                   | Tools                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Session                 | `connect`, `status`, `pullEvents`, `disconnect`, `whoami`, `logout`, `describeProperties`                                             |
+| Workspaces and projects | `listWorkspaces`, `createWorkspace`, `listProjects`, `createProject`, `updateProject`                                                 |
+| Branches                | `listBranches`, `createBranch`                                                                                                        |
+| Pull requests           | `createPullRequest`, `getPullRequest`, `updatePullRequest`, `commentOnPullRequest`                                                    |
+| Canvas                  | one per applicable Action API verb for nodes, pages, components, slots, variants, variables, themes, breakpoints, events, and queries |
+
+Two properties are worth knowing. Mutation tools return only after the sync
+gateway acks the write, so a returned success means persisted, not queued. And
+the server does not provide branch, project, or workspace deletion.
+`pullEvents` returns structured rejection and collaborator action details. It
+also returns merge summaries. Sync and cache signals mean the agent should
+re-query after reconnect catch-up.
+For a read role, the server hides mutation tools and connects to an existing
+branch. It does not create an agent branch.
+Deleting one is irreversible from here, and it is easy for an agent to reach for
+while recovering from its own mistake. That stays in the web UI, where a person
+can see what they are about to destroy.
+
+#### Working against local dev
+
+The published bundle targets `https://zoah.com`. For a local instance, link
+the checkout instead of installing from npm, then sign in against it:
+
+```bash
+zoah login --base-url http://localhost:5070
+```
+
+`connect` accepts a `baseUrl` parameter, and it wins over the saved
+credential. It exists for the clean-workspace case: with no credential file
+yet, the built-in default is a guess, and on a multi-instance dev machine it
+is usually the wrong port. The choice is saved, so later calls agree - a
+session cannot silently straddle two instances, and `status` reports a
+mismatch between the open session and the credential on disk
+(`baseUrlMismatch`) rather than letting one develop unnoticed. Build and link
+steps are in [DEVELOPMENT.md](./DEVELOPMENT.md).
+
+Design and details: [docs/action-api-mcp.md](docs/action-api-mcp.md).
+
+### `zoah import [path]`
+
+Scans first-party React components and sends an import payload to Zoah. It publishes a package and writes project state under `.zoah/`. The default path is `src`.
+
+```bash
+zoah import                       # scans ./src
+zoah import src/components        # scope to a subdirectory
+zoah import --swap                # also rewrite local imports after publish
+zoah import --project-name my-ui  # override the first project name
+zoah import --branch main         # target a specific branch
+zoah import --debug               # also write .zoah/debug/payload.json
+zoah import --print-issues warn   # print issue details at or above this level
+zoah import --dry-run             # preview locally without an API call
+```
+
+The first import creates a project and saves its IDs to `.zoah/config.json`. Later imports use the same project.
+
+Notable flags:
+
+- `--swap`: runs `zoah swap` after a successful import.
+- `--project-name <name>`: sets the first project name. Later imports use the project ID in `.zoah/config.json`.
+- `--branch <name>`: defaults to the project's saved branch (usually `main`).
+- `--base-url <url>`: overrides the URL saved at login.
+- `--print-issues <level>`: also prints full details for every issue at or above `info | warn | error`.
+- `--dry-run`: runs the local pipeline without publishing. It still writes `.zoah/debug/issues.json`.
+
+The CLI skips components imported directly by an entry file (`src/main.tsx`, `src/index.tsx`, etc.). Translating them would blank the running app.
+
+### `zoah preflight [path]`
+
+Runs the import pipeline locally without publishing. It writes `.zoah/debug/issues.json` but does not call the API or change project state.
+
+- preview what a real `zoah import` would do on a checkout you have not published,
+- audit which codes a codebase trips before deciding whether to upgrade the CLI,
+- regenerate the issues snapshot after a source change without re-publishing.
+
+```bash
+zoah preflight                       # scans ./src
+zoah preflight src/components        # scope to a subdirectory
+zoah preflight --print-issues warn   # also print issue details
+```
+
+The full code list, grouped by what the swap actually does (cleanly / visibly degrades / refuses), is documented in `docs/supported-shapes.md` in the repo.
+
+### `zoah swap [path]`
+
+Installs the published Zoah package and wraps your local components. It reads `.zoah/components.json` and `.zoah/manifest.json` from `zoah import`.
+
+```bash
+zoah swap                          # install the package and rewrite imports
+zoah swap --dry-run                # print diffs only
+zoah swap --print-issues warn      # print issue details
+```
+
+The dry-run mode is the safe way to preview what swap will do before letting it touch your source tree.
+
+#### Authenticated installs (`.npmrc` management)
+
+Published packages carry the project's privacy. CLI imports are private by
+default, so the install needs credentials. When the repo's `.npmrc` (and your
+`~/.npmrc`) has no token for the Zoah registry host, swap mints a registry
+API key for the project's organization and manages the file for you:
+
+- The key is requested through the authenticated import API, requires write
+  access in the project's organization, and is **reused** on repeat runs (one
+  key per project + user, not one per invocation). It appears in Project
+  Settings → Package as `CLI import · <project>` and is revocable there.
+- The token line (`//<host>/:_authToken=…`) is written to `<repo>/.npmrc`
+  with owner-only permissions (0600), and `.npmrc` is added to `.gitignore`.
+- **If `.npmrc` is already tracked by git**, `.gitignore` cannot protect it.
+  swap prints a loud warning telling you to `git rm --cached .npmrc` before
+  your next commit.
+- When signed out, the install continues without authentication. Public
+  packages still work. A private package install returns the registry's 401.
+
+## Reading the import output
+
+After each `zoah import` run, the CLI prints a status table for each component:
+
+```
+  Component             Import   Swap
+  ────────────────────  ──────   ────
+  Avatar                █        █
+  Button                █        █         1 error
+  Card                  █ ░      █         2 warnings, 1 info
+  ToastProvider         █        █
+
+  File-level:
+  src/utils.ts          █                  1 warning
+  src/App.tsx           ░                  1 info
+
+  1 error, 2 warnings, 1 info. See .zoah/debug/issues.json
+
+  View in Zoah:  https://zoah.com/projects/<id>/design
+```
+
+Each cell is two glyphs: the **severity slot** on the left summarises the worst outcome for that (row, phase) pair, and the **info-note slot** on the right lights up when any info-level notes accrued.
+
+| Cell         | Meaning                                                                                                                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `█` green    | Phase ran cleanly (component imported successfully, no issues).                                                                                                                                        |
+| `█` yellow   | Phase ran with at least one warning.                                                                                                                                                                   |
+| `█` red      | Phase ran with at least one error.                                                                                                                                                                     |
+| `░` dim      | On a component row, phase didn't reach this row (e.g. swap blocked by an import error). On a File-level row, phase ran with only info-level notes (e.g. an entry file that was intentionally skipped). |
+| blank        | On a File-level row, the phase did not touch this file. Sparse rows leave unused phases empty.                                                                                                         |
+| trailing `░` | The cell has at least one info-level note beside a colored severity block. See the JSON for details.                                                                                                   |
+
+The trailing summary line counts errors, warnings, and info notes (zero-counts are omitted, so a clean run with only info notes still shows e.g. `3 info`). Full per-issue detail is in the JSON snapshot.
+
+### `.zoah/debug/issues.json`
+
+Every run writes all issues to `.zoah/debug/issues.json`, grouped by phase and severity. Shape:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-05-04T18:00:00.000Z",
+  "commitSha": "abc1234+dirty",
+  "summary": { "total": 12 },
+  "phases": {
+    "import":  { "total": 11, "issues": { "error": [...], "warn": [...], "info": [...] } },
+    "package": { "total":  0, "issues": { "error": [],    "warn": [],    "info": []    } },
+    "swap":    { "total":  1, "issues": { "error": [],    "warn": [...], "info": []    } }
+  }
+}
+```
+
+Each issue carries a stable `code` (e.g. `DYNAMIC_CLASSNAME_UNRESOLVED`, `CODEMOD_FILE_REFUSED`), a `target` describing what it applies to (`node` / `component` / `file` / `project`), an optional `location` with a 3-line source snippet, and a `commitSha` stamp. The full code list with severity and phase mappings, grouped by outcome, is documented in `docs/supported-shapes.md` in the repo.
+
+When the import fails (e.g. the server returns 400 because no components were extractable), the CLI still writes this file and prints the table so you can see exactly which components couldn't be imported and why. Pass `--print-issues warn` (or `info`/`error`) to also print snippet + caret detail inline:
+
+```
+  warn  Card · import · DYNAMIC_CLASSNAME_UNRESOLVED  src/Card.tsx:42:18
+    Dynamic className expression couldn't be resolved to styles
+       41 |   const cls = `card-${variant}`;
+       42 |   return <div className={cls}>...</div>;
+                            ^^^
+       43 | }
+```
+
+## What the CLI writes
+
+**Global (per-machine, never inside a project):**
+
+- `~/.zoah/credentials.json`: auth token and base URL (chmod 600). Written by `zoah login` unless a project overrides it.
+
+**Project-local** (paths relative to the project where you run `zoah`). The CLI manages `.zoah/.gitignore` so secrets and debug output stay out of git.
+
+Commit these files. They bind the checkout to the Zoah project:
+
+- `.zoah/config.json`: workspace and project binding, written on the first import.
+- `.zoah/components.json`: component IDs, package exports, and slot anchors.
+- `.zoah/manifest.json`: published package name, version, and registry URL.
+
+Ignored automatically through `.zoah/.gitignore`:
+
+- `.zoah/credentials.json`: local credential from `login --local`.
+- `.zoah/debug/issues.json`: issues from each run, grouped by phase and severity.
+- `.zoah/debug/payload.json`: raw import payload from `--debug`.
+
+The CLI reads old `.opacity` state when the matching `.zoah` file does not exist. New writes use `.zoah`.
+
+## Environment variables
+
+- `ZOAH_BASE_URL`: default base URL when no flag or credential sets one.
+- `ZOAH_BRANCH`: default branch for `import` when `--branch` is not passed.
+
+The old `OPACITY_BASE_URL` and `OPACITY_BRANCH` variables remain compatibility fallbacks.