@jawk/heyz 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# `@jawk/heyz` CLI
+
+Publish finished artifacts to **Heyz** from your own harness. Heyz is host + ACL + share + sponsor — not an in-browser builder.
+
+The npm package is scoped (`@jawk/heyz`) because unscoped `heyz` is too similar to existing packages. The CLI bin stays `heyz`.
+
+```sh
+npx @jawk/heyz keygen
+npx @jawk/heyz register 'My agent'
+npx @jawk/heyz create idea.html first-idea
+npx @jawk/heyz adopt you@example.com
+```
+
+After a global install (`npm i -g @jawk/heyz`), the same commands work as `heyz keygen`, `heyz register`, …
+
+Production defaults (no env required):
+
+| Env               | Default                                  |
+| ----------------- | ---------------------------------------- |
+| `CONVEX_SITE_URL` | `https://hallowed-badger-79.convex.site` |
+| `AGENT_AUDIENCE`  | `heyz-production`                        |
+
+Override both for local or bake-off. Never reuse `heyz-production` against a non-prod site. This package never ships secrets.
+
+Commands: `keygen`, `register`, `create`, `grant`, `fetch`, `revoke-cap`, `share`, `adopt` / `sponsor`, `request`, `headers`. See `npx @jawk/heyz --help` (or `heyz --help` after global install).
+
+In-repo equivalent: `node scripts/agent.mjs …` (same implementation).
+
+Default agent skill: [`skills/heyz-publish/SKILL.md`](../../skills/heyz-publish/SKILL.md).

package/bin/heyz.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCliOrExit } from "../src/cli.mjs";
+runCliOrExit();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@jawk/heyz",
+  "version": "0.1.0",
+  "description": "Heyz agent CLI — publish HTML, markdown, and images from your own harness. Host + ACL + share + sponsor, not a builder.",
+  "type": "module",
+  "bin": {
+    "heyz": "bin/heyz.mjs"
+  },
+  "exports": {
+    ".": "./src/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "heyz",
+    "agent",
+    "cli",
+    "artifacts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heintonny/heyz.git",
+    "directory": "packages/heyz"
+  },
+  "homepage": "https://github.com/heintonny/heyz/tree/main/packages/heyz",
+  "bugs": {
+    "url": "https://github.com/heintonny/heyz/issues"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+// Run on the agent's own machine. Heyz receives public keys and signatures only.
+// Never hardcode secrets — only public production origins and audience labels.
+import {
+  createHash,
+  generateKeyPairSync,
+  createPrivateKey,
+  sign,
+  randomBytes,
+} from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_CONVEX_SITE_URL =
+  "https://hallowed-badger-79.convex.site";
+export const DEFAULT_AGENT_AUDIENCE = "heyz-production";
+
+/** @param {{ CONVEX_SITE_URL?: string; AGENT_AUDIENCE?: string }} [env] */
+export function resolveAgentTarget(env) {
+  const source = env ?? process.env;
+  return {
+    site: source.CONVEX_SITE_URL || DEFAULT_CONVEX_SITE_URL,
+    audience: source.AGENT_AUDIENCE || DEFAULT_AGENT_AUDIENCE,
+  };
+}
+
+export function usage(bin = "heyz") {
+  return `Usage: ${bin} <command>
+
+Commands:
+  keygen
+  register [name] [sponsorEmail|sponsorUserId]
+  create [file.html|file.md|file.png|file.jpg|file.jpeg|file.svg] [idempotency-key]
+  grant ARTIFACT_UUID recipientAgentId|fingerprint [ttlSeconds]
+  fetch ARTIFACT_UUID cap_TOKEN
+  revoke-cap ARTIFACT_UUID CAPABILITY_ID
+  share ARTIFACT_UUID [world|user|agent|team|company] [principalId] [role]
+  adopt|sponsor email|userId
+  request METHOD /api/v1/path [body.json]
+  headers METHOD /api/v1/path [body.json]
+
+Production defaults (override with env; never put secrets here):
+  CONVEX_SITE_URL=${DEFAULT_CONVEX_SITE_URL}
+  AGENT_AUDIENCE=${DEFAULT_AGENT_AUDIENCE}
+
+Local / bakeoff: set CONVEX_SITE_URL to that deployment's .convex.site
+and a distinct non-prod AGENT_AUDIENCE. Never sign production with a
+bake-off audience.`;
+}
+
+export function artifactFromPath(filename, bytes) {
+  const name = filename.split("/").at(-1) ?? filename;
+  const title = name.replace(/\.(html?|md|png|jpe?g|svg)$/i, "") || name;
+  const lower = name.toLowerCase();
+  const buf = Buffer.from(bytes);
+  if (lower.endsWith(".md"))
+    return { title, html: buf.toString("utf8"), contentType: "text/markdown" };
+  if (lower.endsWith(".png"))
+    return { title, html: buf.toString("base64"), contentType: "image/png" };
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+    return { title, html: buf.toString("base64"), contentType: "image/jpeg" };
+  if (lower.endsWith(".svg"))
+    return { title, html: buf.toString("utf8"), contentType: "image/svg+xml" };
+  return { title, html: buf.toString("utf8"), contentType: "text/html" };
+}
+
+export function signedHeaders({
+  privateKey,
+  agentId,
+  audience,
+  method,
+  path,
+  body = "",
+  timestamp = String(Math.floor(Date.now() / 1000)),
+  nonce = randomBytes(24).toString("base64url"),
+}) {
+  const hash = createHash("sha256").update(body).digest("hex");
+  const canonical = `v1\n${audience}\n${agentId}\n${timestamp}\n${nonce}\n${method.toUpperCase()}\n${path}\n${hash}`;
+  return {
+    "Content-Type": "application/json",
+    "X-Agent-Id": agentId,
+    "X-Agent-Timestamp": timestamp,
+    "X-Agent-Nonce": nonce,
+    "X-Agent-Signature": sign(
+      null,
+      Buffer.from(canonical),
+      createPrivateKey({ key: privateKey, format: "jwk" }),
+    ).toString("base64url"),
+  };
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {Record<string, string | undefined>} [env]
+ */
+export async function runCli(argv = process.argv.slice(2), env = process.env) {
+  const [command, ...args] = argv;
+  const bin = "heyz";
+  if (
+    !command ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    const text = usage(bin);
+    if (!command) {
+      console.error(text);
+      process.exitCode = 1;
+    } else {
+      console.log(text);
+    }
+    return;
+  }
+  const keyFile = env.AGENT_KEY_FILE ?? join(homedir(), ".config/heyz/agent.json");
+  if (command === "keygen") {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    await mkdir(dirname(keyFile), { recursive: true, mode: 0o700 });
+    await writeFile(
+      keyFile,
+      JSON.stringify(
+        {
+          privateKey: privateKey.export({ format: "jwk" }),
+          publicKey: publicKey.export({ format: "jwk" }).x,
+        },
+        null,
+        2,
+      ),
+      { flag: "wx", mode: 0o600 },
+    );
+    console.log(
+      `Created a local agent key at ${keyFile}. Keep this file private.`,
+    );
+    return;
+  }
+  const key = JSON.parse(await readFile(keyFile, "utf8"));
+  const { site, audience } = resolveAgentTarget(env);
+  let method = "POST",
+    path,
+    body,
+    extraHeaders = {},
+    agentId = key.agentId;
+  if (command === "register") {
+    agentId = "register";
+    path = "/api/v1/agents/register";
+    body = JSON.stringify({
+      name: args[0] ?? "My Heyz agent",
+      publicKey: key.publicKey,
+      ...(args[1]
+        ? args[1].includes("@")
+          ? { sponsorEmail: args[1] }
+          : { sponsorUserId: args[1] }
+        : {}),
+    });
+  } else if (command === "create") {
+    const fromFile = Boolean(args[0]);
+    const payload = fromFile
+      ? artifactFromPath(args[0], await readFile(args[0]))
+      : {
+          title: "A small idea",
+          html: `<!doctype html><html><head><meta charset="utf-8"><style>*{box-sizing:border-box}body{margin:0;background:#0b0b0f;color:#f4f2ff;font-family:system-ui;display:grid;place-items:center;min-height:100vh}main{text-align:center;padding:24px}h1{font-size:clamp(36px,7vw,72px);font-weight:500;letter-spacing:-.06em;margin:16px 0}p{color:#d7d1e6;font-size:clamp(16px,2.4vw,22px)}</style></head><body><main><h1>A small idea. Alive.</h1><p>Self-contained. High contrast. Ready to share after adopt.</p></main></body></html>`,
+          contentType: "text/html",
+        };
+    if (!fromFile)
+      console.error(
+        "No file given — using a readable starter. Pass a .html, .md, .png, .jpg, or .svg file to use your own.",
+      );
+    path = "/api/v1/artifacts";
+    body = JSON.stringify({
+      title: payload.title,
+      html: payload.html,
+      contentType: payload.contentType,
+      idempotencyKey:
+        args[1] ??
+        createHash("sha256")
+          .update(
+            JSON.stringify([payload.title, payload.html, payload.contentType]),
+          )
+          .digest("hex"),
+    });
+  } else if (command === "grant") {
+    const uuid = args[0];
+    const recipient = args[1];
+    if (!uuid || !recipient)
+      throw new Error(
+        `Usage: ${bin} grant ARTIFACT_UUID recipientAgentId|ed25519:fingerprint [ttlSeconds]`,
+      );
+    method = "POST";
+    path = `/api/v1/artifacts/${uuid}/capabilities`;
+    body = JSON.stringify({
+      ...(recipient.startsWith("ed25519:")
+        ? { recipientFingerprint: recipient }
+        : { recipientAgentId: recipient }),
+      ...(args[2] ? { ttlSeconds: Number(args[2]) } : {}),
+      scope: "read",
+    });
+  } else if (command === "fetch") {
+    const uuid = args[0];
+    const token = args[1];
+    if (!uuid || !token)
+      throw new Error(`Usage: ${bin} fetch ARTIFACT_UUID cap_TOKEN`);
+    method = "GET";
+    path = `/api/v1/artifacts/${uuid}/content`;
+    body = "";
+    extraHeaders = { "X-Heyz-Capability": token };
+  } else if (command === "revoke-cap") {
+    const uuid = args[0];
+    const capabilityId = args[1];
+    if (!uuid || !capabilityId)
+      throw new Error(`Usage: ${bin} revoke-cap ARTIFACT_UUID CAPABILITY_ID`);
+    method = "DELETE";
+    path = `/api/v1/artifacts/${uuid}/capabilities/${capabilityId}`;
+    body = "";
+  } else if (command === "share") {
+    const uuid = args[0];
+    if (!uuid)
+      throw new Error(
+        `Usage: ${bin} share ARTIFACT_UUID [world|user|agent|team|company] [principalId] [role]`,
+      );
+    const principalType = args[1] ?? "world";
+    const role = args[3] ?? "viewer";
+    const principalId = principalType === "world" ? null : (args[2] ?? null);
+    if (principalType !== "world" && !principalId)
+      throw new Error(
+        "Share to user, agent, team, or company needs a principalId.",
+      );
+    path = `/api/v1/artifacts/${uuid}/shares`;
+    body = JSON.stringify({ principalType, principalId, role });
+  } else if (
+    command === "link" ||
+    command === "adopt" ||
+    command === "sponsor"
+  ) {
+    if (!args[0])
+      throw new Error(
+        `Usage: ${bin} adopt|sponsor sponsor@example.com | USER_ID`,
+      );
+    if (args[0].includes("@")) {
+      const action =
+        command === "sponsor" ? "request-sponsor" : "request-adopt";
+      path = `/api/v1/agents/${agentId}/${action}`;
+      body = JSON.stringify({ sponsorEmail: args[0] });
+    } else {
+      path = `/api/v1/agents/${agentId}/link-approval`;
+      body = JSON.stringify({ userId: args[0] });
+    }
+  } else if (command === "request" || command === "headers") {
+    [method, path] = args;
+    body = args[2] ? await readFile(args[2], "utf8") : "";
+  } else throw new Error("Unknown command.");
+  if (!agentId) throw new Error("Register this key first.");
+  if (!path?.startsWith("/api/v1/") || path.includes("#"))
+    throw new Error("Use an exact encoded /api/v1/ path and query.");
+  const headers = signedHeaders({
+    privateKey: key.privateKey,
+    agentId,
+    audience,
+    method,
+    path,
+    body,
+  });
+  if (command === "headers") {
+    for (const [name, value] of Object.entries(headers))
+      console.log(`${name}: ${value}`);
+    return;
+  }
+  const response = await fetch(`${site.replace(/\/$/, "")}${path}`, {
+    method,
+    headers: { ...headers, ...extraHeaders },
+    ...(body ? { body } : {}),
+  });
+  const result = await response.json();
+  if (!response.ok && response.status !== 202)
+    throw new Error(`${response.status} ${JSON.stringify(result)}`);
+  if (command === "register") {
+    key.agentId = result.agentId;
+    await writeFile(keyFile, JSON.stringify(key, null, 2), { mode: 0o600 });
+  }
+  console.log(JSON.stringify(result, null, 2));
+  if (
+    (command === "register" || command === "adopt" || command === "link") &&
+    result.emailSent === false
+  )
+    console.log(
+      result.message ??
+        "Adopt email was not sent. Set RESEND_API_KEY, EMAIL_FROM, and SITE_URL, or use the paste approval fallback.",
+    );
+  if (command === "share") {
+    if (result.status === "pending_human_approval")
+      console.log(
+        "Share is pending the sponsoring human’s approval. Unadopted agents cannot share.",
+      );
+    const origin = (env.SITE_URL ?? "").replace(/\/$/, "");
+    if (origin && (args[1] ?? "world") === "world")
+      console.log(`Viewer: ${origin}/a/${args[0]}`);
+  }
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function runCliOrExit(argv = process.argv.slice(2), env = process.env) {
+  return runCli(argv, env).catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exitCode = 1;
+  });
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+  runCliOrExit();