@unravel-tech/thing 0.4.0 → 0.5.0

package/LICENSE

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

@@ -3,22 +3,22 @@
 CLI for [thing](https://usething.ai): push, version, and share artifacts (HTML pages, Markdown docs, standalone images and PDFs) from coding agents.
 
 ```sh
-npm i -g @unravel-tech/thing
-thing login                          # defaults to https://usething.ai
-thing push report.html --json
-thing push notes.md --json           # Markdown gets a styled reader view
-thing push chart.png --json          # images and PDFs too
+npx -y @unravel-tech/thing push report.html
 ```
 
+That first push opens browser approval, waits for sign-in, then resumes and
+prints the durable URL. Markdown, images, and PDFs work the same way. Install
+globally if you use it often: `npm i -g @unravel-tech/thing`.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `thing login [--server url]` | Device-code login; stores a token (does not pin a team) |
+| `thing login [--server url] [--no-browser]` | Explicit device-code login; opens browser approval and stores a token |
 | `thing logout` / `thing whoami` | Clear / show the current identity and where pushes land |
 | `thing default [team] [--clear]` | Show or set your server-side default push target (used when no `--team` is given, from any machine) |
 | `thing use <team> [project]` | Set a local active team/project override for this machine |
-| `thing push <file.html\|.md\|.pdf\|.png\|.jpg\|.gif\|.webp> [--name x] [--team t] [--project p] [--visibility v]` | Push a new immutable version (HTML, Markdown, or image/PDF), print the served URL |
+| `thing push <file.html\|.md\|.pdf\|.png\|.jpg\|.gif\|.webp> [--name x] [--team t] [--project p] [--visibility v]` | Authenticate if needed, then push a new immutable version and print the served URL |
 | `thing list` | List artifacts you can see |
 | `thing versions <name>` | Version history for an artifact |
 | `thing rollback <name> <n>` | Point latest back to version n |
@@ -26,6 +26,9 @@ thing push chart.png --json          # images and PDFs too
 | `thing mcp` | Run a Model Context Protocol server over stdio (tools: `push_artifact`, `list_artifacts`, `whoami`) |
 
 Every command accepts `--json` for machine-readable output.
+An unauthenticated `push --json` emits newline-delimited authentication status;
+the final JSON object is always the push result. Use `--no-login` to fail fast
+instead of starting interactive authentication, such as in CI.
 
 Visibility values: `private`, `team`, `anyone-with-link` (prints a tokened share URL), `public`.
 
@@ -55,6 +58,20 @@ into your client's MCP config.
 }
 ```
 
+On a machine that has Bun but no Node, swap `npx` for `bunx`:
+
+```json
+{
+  "mcpServers": {
+    "thing": {
+      "command": "bunx",
+      "args": ["-y", "@unravel-tech/thing", "mcp"],
+      "env": { "THING_TOKEN": "paste-your-token-here" }
+    }
+  }
+}
+```
+
 The server exposes three tools: `push_artifact` to publish a file or inline
 content and get back a link, `list_artifacts` to see what you have, and
 `whoami` to check which account and team you are pushing to.
@@ -62,4 +79,13 @@ content and get back a link, `list_artifacts` to see what you have, and
 If you already ran `thing login`, the stored credential is used and
 `THING_TOKEN` can be left out.
 
-Requires Node >= 18 or Bun. No runtime dependencies.
+## Runtimes
+
+Node >= 18 or Bun, no runtime dependencies. The `thing` executable launches under
+whichever of the two is on your PATH (Node first), so a global install works on a
+machine that has never installed Node:
+
+```sh
+bun i -g @unravel-tech/thing
+thing login
+```

package/package.json

@@ -3,8 +3,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.0",
-  "description": "CLI for thing: push, version, and share artifacts (HTML, Markdown, images, PDFs) from coding agents.",
+  "version": "0.5.0",
+  "description": "Artifacts for any coding agent. Publish what Claude Code, Codex, Cursor or Gemini CLI builds to a durable link, with versions and comments on the page.",
+  "mcpName": "io.github.unravel-team/thing",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,18 +18,26 @@
   },
   "files": [
     "src/index.js",
-    "README.md"
+    "README.md",
+    "server.json"
   ],
   "keywords": [
     "artifacts",
     "html",
+    "markdown",
     "cli",
     "agents",
-    "claude-code"
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "share",
+    "publish",
+    "codex",
+    "cursor"
   ],
   "scripts": {
-    "smoke": "bun test/cli-smoke.mjs",
-    "typecheck": "bun --print \"await import('./src/index.js'); 'ok'\""
+    "smoke": "node test/cli-smoke.mjs",
+    "typecheck": "node --input-type=module -e \"await import('./src/index.js'); console.log('ok')\""
   },
   "engines": {
     "node": ">=18"

package/server.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.unravel-team/thing",
+  "title": "thing",
+  "description": "Artifacts for any coding agent: a durable link with versions, diffs, and comments on the page.",
+  "version": "0.5.0",
+  "repository": {
+    "url": "https://github.com/unravel-team/thing-cli",
+    "source": "github"
+  },
+  "websiteUrl": "https://usething.ai",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@unravel-tech/thing",
+      "version": "0.5.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "mcp",
+          "valueHint": "mcp",
+          "description": "Run the CLI as a Model Context Protocol server over stdio",
+          "isRequired": true
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "THING_TOKEN",
+          "description": "API token from usething.ai, under Settings then Tokens. Lets the server publish on your behalf with no terminal login.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "THING_SERVER",
+          "description": "Base URL of the thing server. Defaults to https://usething.ai; only set this for a self-hosted instance.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/index.js

@@ -1,4 +1,11 @@
-#!/usr/bin/env node
+#!/bin/sh
+':' //# ; rt="$(command -v node || command -v bun)"; [ -n "$rt" ] || { echo "thing: needs Node >= 18 or Bun on PATH" >&2; exit 127; }; exec "$rt" "$0" "$@"
+// The shebang is /bin/sh, not `env node`, so a global install never hard-requires
+// a `node` binary: bun links its global bins straight at this file, and the kernel
+// would otherwise run `env node` and fail for anyone who installed with `bun i -g`
+// and has no node. Line 2 is a command to sh (exec the first runtime we find, node
+// first so npm installs behave exactly as before) and a no-op string plus comment
+// to JS, so the file stays valid ESM once the runtime re-reads it.
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -6,7 +13,10 @@ import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
 const DEFAULT_SERVER = process.env.THING_SERVER || "https://usething.ai";
-let clientName = "thing-cli/0.3.0";
+// One source for the version: hardcoding it here meant the MCP handshake and
+// the analytics client header both kept reporting 0.3.0 releases later.
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+let clientName = `thing-cli/${VERSION}`;
 const VISIBILITIES = new Set(["team", "public"]);
 
 class CliError extends Error {
@@ -102,7 +112,7 @@ function context(state, flags = {}) {
 }
 
 function requireToken(ctx) {
-  if (!ctx.token) throw new CliError("Not logged in. Run `thing login` first.");
+  if (!ctx.token) throw new CliError("Not logged in. Run `thing login`, or remove `--no-login` to authenticate during push.");
 }
 
 function slugify(input) {
@@ -167,10 +177,35 @@ async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function login(parsed, state, io) {
-  const server = stripSlash(parsed.flags.server || state.global.server || DEFAULT_SERVER);
-  const device = await api({ server }, "/api/v1/auth/device/code", { method: "POST", body: {} });
-  const loginMessage = `Open ${device.verification_uri_complete || device.verification_uri}\nEnter code: ${device.user_code}`;
+function openerCommand(url) {
+  if (process.platform === "darwin") return ["open", [url]];
+  if (process.platform === "win32") return ["cmd", ["/c", "start", "", url]];
+  return ["xdg-open", [url]];
+}
+
+function openBrowser(url) {
+  try {
+    const [cmd, args] = openerCommand(url);
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    // A missing desktop opener should not end the login flow: the URL is also
+    // printed, so headless and SSH users still have a path forward.
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Best effort only; the printed URL is the fallback.
+  }
+}
+
+async function login(parsed, state, io, options = {}) {
+  const server = context(state, parsed.flags).server;
+  const device = await api({ server }, "/api/v1/auth/device/code", {
+    method: "POST",
+    body: { intent: options.intent || "login" }
+  });
+  const verificationUrl = device.verification_uri_complete || device.verification_uri;
+  const env = state.env ?? process.env;
+  const shouldOpenBrowser = !parsed.flags["no-browser"] && env.THING_NO_BROWSER !== "1";
+  const loginMessage = `${shouldOpenBrowser ? "Opening" : "Open"} ${verificationUrl}\nEnter code: ${device.user_code}\nWaiting for approval...`;
   output(io, parsed.json, {
     server,
     verificationUri: device.verification_uri,
@@ -179,9 +214,10 @@ async function login(parsed, state, io) {
     expiresIn: device.expires_in,
     interval: device.interval
   }, loginMessage);
+  if (shouldOpenBrowser) openBrowser(verificationUrl);
 
   const deadline = Date.now() + (Number(device.expires_in || 900) * 1000);
-  const interval = Math.max(250, Number(process.env.THING_POLL_INTERVAL_MS || Math.max(1, Number(device.interval || 5)) * 1000));
+  const interval = Math.max(250, Number(env.THING_POLL_INTERVAL_MS || Math.max(1, Number(device.interval || 5)) * 1000));
   let tokenResult = null;
   while (Date.now() < deadline) {
     await sleep(interval);
@@ -221,6 +257,15 @@ async function login(parsed, state, io) {
     user: whoami.user,
     defaultTeam
   }, `Logged in as ${whoami.user.email}${defaultTeam ? ` (pushes default to ${defaultTeam})` : ""}`);
+
+  return context(state, parsed.flags);
+}
+
+async function pushContext(parsed, state, io) {
+  const ctx = context(state, parsed.flags);
+  if (ctx.token) return ctx;
+  if (parsed.flags["no-login"]) requireToken(ctx);
+  return login(parsed, state, io, { intent: "push" });
 }
 
 async function logout(parsed, state, io) {
@@ -346,10 +391,10 @@ async function pushToServer(ctx, { doc, name, visibility }) {
 async function push(parsed, state, io) {
   const [file] = parsed.positionals;
   if (!file) throw new CliError("Usage: thing push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility team|public]");
-  const ctx = context(state, parsed.flags);
-  requireToken(ctx);
   const path = resolve(file);
   const doc = docFromFile(path);
+  if (parsed.flags.visibility && !VISIBILITIES.has(parsed.flags.visibility)) throw new CliError("Invalid visibility. Use team or public.");
+  const ctx = await pushContext(parsed, state, io);
   const result = await pushToServer(ctx, {
     doc,
     name: parsed.flags.name || titleFromFile(path),
@@ -383,12 +428,6 @@ async function rollback(parsed, state, io) {
   output(io, parsed.json, { artifact, ...result }, `Rolled back ${artifact.teamSlug}/${artifact.slug} to v${result.latestVersion}`);
 }
 
-function openerCommand(url) {
-  if (process.platform === "darwin") return ["open", [url]];
-  if (process.platform === "win32") return ["cmd", ["/c", "start", "", url]];
-  return ["xdg-open", [url]];
-}
-
 async function openCommand(parsed, state, io) {
   const [name] = parsed.positionals;
   if (!name) throw new CliError("Usage: thing open <name>");
@@ -397,9 +436,7 @@ async function openCommand(parsed, state, io) {
   const artifact = await resolveArtifact(ctx, name);
   const url = `${ctx.server}/${artifact.teamSlug}/${artifact.slug}`;
   if (!parsed.json && !parsed.flags["no-browser"]) {
-    const [cmd, args] = openerCommand(url);
-    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.unref();
+    openBrowser(url);
   }
   output(io, parsed.json, { url, artifact }, url);
 }
@@ -414,7 +451,7 @@ const MCP_TOOLS = [
   {
     name: "push_artifact",
     description:
-      "Publish a file as a thing artifact and get a live, shareable URL. Every push creates a new immutable version. Pass either `path` (any supported file: html, md, pdf, png, jpg, gif, webp) or inline `content` with a `filename` (html or md).",
+      "Use this whenever the user wants to share, send, show, or publish something you produced: a report, a dashboard, a prototype, a Markdown doc, a PDF, an image. Publishes it to a durable URL that stays live, and returns the link. Pushing the same name again creates a new version at the same link rather than a second link, so prefer reusing a name over inventing one. Pass either `path` (html, md, pdf, png, jpg, gif, webp) or inline `content` with a `filename` (html or md).",
     inputSchema: {
       type: "object",
       properties: {
@@ -430,7 +467,8 @@ const MCP_TOOLS = [
   },
   {
     name: "list_artifacts",
-    description: "List the artifacts the logged-in user can see, with team, visibility, and title.",
+    description:
+      "Use this to find a link the user published earlier, or to check whether something is already published before pushing it again. Lists artifacts the signed-in user can see, with team, visibility and title.",
     inputSchema: {
       type: "object",
       properties: {
@@ -441,7 +479,8 @@ const MCP_TOOLS = [
   },
   {
     name: "whoami",
-    description: "Show the logged-in thing user, the server, and where pushes land by default.",
+    description:
+      "Use this to confirm the user is signed in and which team will own a new artifact. Shows the account, the server, and where pushes land when no team is named.",
     inputSchema: { type: "object", properties: {} }
   }
 ];
@@ -488,14 +527,14 @@ async function mcpTool(state, parsed, name, args) {
 }
 
 async function mcp(parsed, state, io) {
-  clientName = "thing-mcp/0.3.0";
+  clientName = `thing-mcp/${VERSION}`;
   const respond = (id, body) => io.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, ...body })}\n`);
   const handle = async (req) => {
     if (req.method === "initialize") {
       return {
         protocolVersion: req.params?.protocolVersion || "2025-06-18",
         capabilities: { tools: {} },
-        serverInfo: { name: "thing", version: "0.3.0" }
+        serverInfo: { name: "thing", version: VERSION }
       };
     }
     if (req.method === "tools/list") return { tools: MCP_TOOLS };
@@ -541,12 +580,12 @@ function usage() {
   return `Usage: thing <command> [options]
 
 Commands:
-  login [--server url]
+  login [--server url] [--no-browser]
   logout
   whoami
   use <team> [project]
   default [team] [--clear]
-  push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility team|public]
+  push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility team|public] [--no-login] [--no-browser]
   list
   versions <name>
   rollback <name> <version>