magic-spells 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magic Spells
+
+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.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# magic-spells
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`magic`: one command line and MCP server for Magic Spells' hosted services. Node 24 or newer.
+
+```sh
+npx -y magic-spells --help      # or: npm i -g magic-spells
+```
+
+## Sign in with a product key
+
+```sh
+magic login --product-key            # paste the key at the hidden prompt
+echo "$KEY" | magic login --product-key pyramid   # or pipe it (CI)
+magic whoami                         # where each key comes from, and who it is
+magic logout                         # forget every stored key (--product <p> for one)
+```
+
+Keys are read from the prompt or stdin, never from arguments, and stored in the macOS
+Keychain (service `io.magicspells.cli`) or, elsewhere, a mode-0600 file in
+`~/.config/magic/credentials.json`. A key in the environment wins over a stored one.
+`magic pyramid login` is the browser sign-in that mints a Pyramid key for you.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `magic login --product-key [<product>]` | store a product key (product detected from the key's prefix) |
+| `magic logout [--product <p>]` | forget stored keys |
+| `magic whoami [--json]` | per product: key source (env, keychain, file, none), masked key, identity |
+| `magic doctor [--json]` | Node, credential store, and per product: API reachable, key present, product checks |
+| `magic mcp [--products a,b]` | the MCP server over stdio: every product's tools, prefixed (`pyramid_*`) |
+| `magic pyramid <noun> <verb>` | Pyramid: `task next`, `task move WEB-42 --status "In Review"`, `task comment`, `project list`, `whoami`, … (`magic pyramid --help`) |
+
+Global flags: `--json`, `--yes/-y`, `--no-color`, `--quiet/-q`, `--workspace <handle>`.
+Output is JSON whenever stdout is not a terminal; errors go to stderr as
+`{ "error": { "code", "message", "hint", "product" } }`.
+
+## MCP
+
+```sh
+claude mcp add magic -- npx -y magic-spells mcp
+```
+
+A product without a key still lists its tools; their calls answer `not_logged_in` until a
+key is stored, without restarting the server.
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `MAGIC_<PRODUCT>_KEY` | the product's key, e.g. `MAGIC_PYRAMID_KEY=pyramid_…`; never stored |
+| `MAGIC_<PRODUCT>_URL` | the product's API base URL, e.g. `MAGIC_PYRAMID_URL` |
+| `MAGIC_ALLOW_DESTRUCTIVE=1` | allow destructive operations (with `--yes`, or `yes: true` in MCP) |
+| `MAGIC_CREDENTIALS_FILE=1` | store keys in the 0600 file instead of the OS keychain |
+| `XDG_CONFIG_HOME` | where `magic/` (config and credentials file) lives |
+| `NO_COLOR` | no colour |
+
+## Exit codes
+
+Scripts branch on the exit code, or on `error.code` in the JSON envelope: 0 ok, 1 unknown,
+2 usage, 3 not logged in or bad key, 4 permission denied, 5 not found, 6 ambiguous name,
+7 validation or conflict, 8 destructive action disabled, 9 rate limited, 10 network,
+11 product unavailable. The table lives in
+[`packages/kit/src/errors.ts`](https://github.com/magic-spells/cli/blob/main/packages/kit/src/errors.ts)
+(`exitCodeFor`).
+
+MIT licensed.

package/bin/magic.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// The `magic` binary. Plain JS so the Node version check runs before any modern syntax
+// or dependency loads; everything else lives in the compiled shell (src/main.ts).
+
+const major = Number(process.versions.node.split('.')[0]);
+if (major < 24) {
+	process.stderr.write(`magic needs Node 24 or newer (this is Node ${process.versions.node}).\n`);
+	process.exit(1);
+}
+
+const { run } = await import('../dist/main.js');
+process.exitCode = await run(process.argv.slice(2));