visual-companion 0.3.1

package/PUBLISHING.md

@@ -0,0 +1,76 @@
+# Publishing the npm placeholder
+
+`visual-companion` on npm is a **name reservation**, not a distribution channel.
+The real program is a single static binary; see the project README.
+
+This is deliberately not wired into CI. Re-publishing is a rare, manual act, and
+a workflow that fires on every tag would burn versions on an empty package.
+
+## Why a placeholder at all
+
+The name is worth more than the work of claiming it. Anyone searching npm for a
+"visual companion" or "MCP brainstorming" tool would otherwise find a squatter,
+and the cost of reclaiming a name is far higher than the cost of holding it.
+
+## One-time setup
+
+The token in `~/.npmrc` must be able to publish the `visual-companion` package.
+A stale token fails in a confusing way: `npm publish` reports
+
+```
+404 Not Found - PUT https://registry.npmjs.org/visual-companion
+```
+
+That is npm's response to a token it does not accept — it deliberately does not
+distinguish "no such package" from "you may not create it", so a 404 on PUT
+almost always means the token, not the name.
+
+Check the token before blaming anything else:
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+`{}` or a 401 means the token is revoked or expired. Mint a new **granular
+access token** with *Read and write* permission at
+<https://www.npmjs.com/settings/~/tokens>, and put it in `~/.npmrc`:
+
+```
+//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxx
+```
+
+Note that `~/.npmrc` may point `registry` at a mirror (npmmirror, for instance).
+`whoami` and `publish` then go to the mirror, which does not know about your
+npmjs token. Always pass the registry explicitly, as the commands below do.
+
+## Publishing
+
+```bash
+cd packaging/npm
+npm version <x.y.z> --no-git-tag-version   # keep in step with the Git tag
+npm publish --registry=https://registry.npmjs.org/
+```
+
+Then verify:
+
+```bash
+npm view visual-companion version --registry=https://registry.npmjs.org/
+```
+
+## Replacing the placeholder with a real package
+
+If npm distribution is ever wanted, the pattern is one package per platform
+holding the binary, plus this package as the entry point:
+
+```
+visual-companion                bin -> launcher.js, optionalDependencies on the below
+visual-companion-darwin-arm64   the binary
+visual-companion-linux-x64      the binary
+...
+```
+
+The launcher picks the artifact for `process.platform` / `process.arch` and
+spawns it. Weigh that against the point of the project first: it exists so the
+target machine needs **no runtime**, and a machine without Node cannot use an
+npm package. Users who do have Node are already served by
+`scripts/install.sh` in one line.

package/README.md

@@ -0,0 +1,39 @@
+# visual-companion (placeholder)
+
+**This package intentionally contains no code.** It exists so the name is not
+taken by something unrelated before the real npm packaging lands.
+
+The actual program is an MCP stdio server that gives a coding agent a browser
+tab for showing mockups, diagrams, and visual options during a brainstorming
+session. The agent pushes HTML fragments; you look and click; the agent reads
+the clicks back on its next turn.
+
+## Install the real thing
+
+It ships as a **single static binary** with the browser assets embedded — no
+Node, no npm, no runtime. The installer detects your platform, verifies the
+SHA256, installs to `~/.local/bin`, and clears the macOS quarantine flag:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ystyle/visual-companion/main/scripts/install.sh | bash
+```
+
+Or download the artifact for your platform from the
+[releases page](https://github.com/ystyle/visual-companion/releases).
+
+## Configure your agent
+
+```bash
+claude mcp add visual-companion -- visual-companion
+```
+
+No path argument is needed: the server discovers your workspace over MCP roots
+when a companion starts.
+
+See the [project README](https://github.com/ystyle/visual-companion#readme) for
+screen-authoring conventions, the design/version scheme, and how it works.
+
+## License
+
+MIT. The browser assets are adapted from
+[Superpowers](https://github.com/obra/superpowers) by Jesse Vincent.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "visual-companion",
+  "version": "0.3.1",
+  "description": "MCP browser companion for visual brainstorming. Placeholder package — the real distribution is a single static binary with no runtime dependency.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "brainstorming",
+    "mockups",
+    "visual",
+    "design"
+  ],
+  "homepage": "https://github.com/ystyle/visual-companion",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ystyle/visual-companion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ystyle/visual-companion/issues"
+  },
+  "license": "MIT",
+  "author": "ystyle",
+  "files": [
+    "README.md",
+    "PUBLISHING.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"const p=require('./package.json');if(!/^\\d+\\.\\d+\\.\\d+/.test(p.version)){console.error('bad version');process.exit(1)}\""
+  }
+}