@hypersocial/decks-cli 0.1.1 → 0.1.3

package/README.md

@@ -2,6 +2,12 @@
 
 Command-line client for Hypersocial Decks live analytics and share management.
 
+Most users should install the friendlier package name:
+
+```bash
+pnpm dlx hyperdecks whoami
+```
+
 This package targets production by default:
 
 ```bash
@@ -10,6 +16,7 @@ pnpm dlx @hypersocial/decks-cli whoami
 pnpm dlx @hypersocial/decks-cli deck list
 pnpm dlx @hypersocial/decks-cli deck stats netflix
 pnpm dlx @hypersocial/decks-cli activity --limit 20
+pnpm dlx @hypersocial/decks-cli skills install
 ```
 
 Global install:
@@ -54,6 +61,7 @@ share rm <token>
 share url <token>
 
 recipient archive|unarchive <name>
+skills install [--path <dir>] [--force]
 activity [--deck <slug>] [--limit <n>] [--json]
 ```
 

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
+  "main": "./src/commands.mjs",
+  "exports": {
+    ".": "./src/commands.mjs",
+    "./commands": "./src/commands.mjs",
+    "./ops": "./src/ops.mjs",
+    "./runtime": "./src/runtime.mjs",
+    "./src/commands.mjs": "./src/commands.mjs",
+    "./src/ops.mjs": "./src/ops.mjs",
+    "./src/runtime.mjs": "./src/runtime.mjs",
+    "./package.json": "./package.json"
+  },
   "license": "UNLICENSED",
   "bin": {
     "decks": "bin/decks.mjs"
@@ -10,6 +21,7 @@
   "files": [
     "bin/",
     "src/",
+    "skills/",
     "README.md"
   ],
   "engines": {

package/skills/hyperdecks/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: hyperdecks
+description: Use when working with Hypersocial Decks, Hyperdecks CLI, production deck analytics, recipient share links, deck activity, MCP deck tools, or real-world/customer-facing deck checks. Prefer production for real activity and analytics; use development only for local implementation/testing when explicitly requested.
+---
+
+# Hyperdecks
+
+## Overview
+
+Hyperdecks is the CLI and MCP surface for Hypersocial Decks live analytics,
+recipient links, and deck activity. Treat real recipient activity, live deck
+stats, customer-facing links, and "what happened" questions as production work.
+
+## Target Selection
+
+- Prefer production for real-world questions and actions. The published CLI is
+  prod-first, so `hyperdecks whoami`, `hyperdecks deck list`, and
+  `hyperdecks activity` already target prod.
+- Use development only for implementation/testing when the user explicitly asks
+  for dev/local behavior. Dev requires a Convex URL with `--dev --convex <url>`
+  or `HSDECKS_CONVEX_URL`.
+- Do not use `decks.localhost` for production checks.
+
+## CLI Workflow
+
+Use the installed CLI when available:
+
+```bash
+hyperdecks whoami
+hyperdecks deck list
+hyperdecks activity --limit 10
+hyperdecks deck stats <slug>
+hyperdecks share list <slug>
+```
+
+If the CLI is missing, recommend:
+
+```bash
+pnpm dlx hyperdecks <command>
+```
+
+If authentication is missing, run or ask the user to run:
+
+```bash
+hyperdecks login
+```
+
+## Safety
+
+- For read-only inspection, run commands directly and summarize the important
+  output.
+- For share creation, revocation, deletion, recipient archive/unarchive, or other
+  live changes, state the action and target clearly before executing when user
+  intent is ambiguous.
+- Avoid printing full share tokens unless the user needs the exact URL/token.

package/skills/hyperdecks/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyperdecks"
+  short_description: "Use prod Hyperdecks CLI and MCP safely"
+  default_prompt: "Use $hyperdecks to inspect production deck activity."

package/src/commands.mjs

@@ -1,4 +1,4 @@
-import { login, logout, openBrowser, parse, target, VERSION } from "./runtime.mjs";
+import { installHyperdecksSkill, login, logout, openBrowser, parse, target, VERSION } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
 
 const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
@@ -155,6 +155,8 @@ commands:
   deck list|stats|open
   share new|list|on|off|rm|url
   recipient archive|unarchive
+  skill install [--path <dir>] [--force]
+  skills install [--path <dir>] [--force]
   activity [--deck <slug>] [--limit <n>] [--json]
 
 global:
@@ -193,6 +195,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     "share url": () => shareUrl(rest, opts),
     "recipient archive": () => recipientArchive(rest, opts, true),
     "recipient unarchive": () => recipientArchive(rest, opts, false),
+    "skill install": () => installHyperdecksSkill(opts),
+    "skills install": () => installHyperdecksSkill(opts),
     activity: () => activity(pos.slice(1), opts),
   };
 

package/src/runtime.mjs

@@ -1,13 +1,14 @@
 import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.1.1";
+export const VERSION = "0.1.3";
 
 export const PROD = {
   name: "prod",
@@ -37,10 +38,12 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "json", "require-email", "help", "version"]);
+const BOOL = new Set(["prod", "dev", "json", "require-email", "help", "version", "force"]);
 
 export const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
 export const CRED_FILE = join(CRED_DIR, "credentials.json");
+const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+const PACKAGED_SKILL_DIR = join(SRC_DIR, "..", "skills", "hyperdecks");
 
 export function parse(args) {
   const opts = {};
@@ -167,6 +170,31 @@ export function openBrowser(url) {
   execFile(cmd, args, () => {});
 }
 
+export function defaultSkillRoot() {
+  return process.env.CODEX_HOME ? join(process.env.CODEX_HOME, "skills") : join(homedir(), ".codex", "skills");
+}
+
+export function installHyperdecksSkill(opts = {}) {
+  const root = opts.path || opts.dir || defaultSkillRoot();
+  const dest = join(root, "hyperdecks");
+  if (!existsSync(PACKAGED_SKILL_DIR)) {
+    throw new Error(`packaged hyperdecks skill not found at ${PACKAGED_SKILL_DIR}`);
+  }
+  if (existsSync(dest)) {
+    if (!opts.force) {
+      console.log(`hyperdecks skill already installed at ${dest}`);
+      console.log("Run `hyperdecks skills install --force` to refresh it.");
+      return { installed: false, path: dest };
+    }
+    rmSync(dest, { recursive: true, force: true });
+  }
+  mkdirSync(root, { recursive: true });
+  cpSync(PACKAGED_SKILL_DIR, dest, { recursive: true });
+  console.log(`OK installed hyperdecks skill to ${dest}`);
+  console.log("Restart Codex or start a new session if the skill list is already loaded.");
+  return { installed: true, path: dest };
+}
+
 async function verifyAndStampEmail(t, opts) {
   const c = await client(opts);
   const who = await c.query(api.decks.whoami, {});