peekable 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,3 @@
+import { type ShareConfig } from "./config.js";
+export declare function api(config: ShareConfig, method: string, path: string, body?: unknown): Promise<any>;
+export declare function apiNoAuth(url: string, method: string, path: string, body?: unknown): Promise<any>;

package/dist/api.js

@@ -0,0 +1,27 @@
+export async function api(config, method, path, body) {
+    const res = await fetch(`${config.url}/api${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${config.api_key}`,
+            "Content-Type": "application/json",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(err.error ?? res.statusText);
+    }
+    return res.json();
+}
+export async function apiNoAuth(url, method, path, body) {
+    const res = await fetch(`${url}/api${path}`, {
+        method,
+        headers: { "Content-Type": "application/json" },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(err.error ?? res.statusText);
+    }
+    return res.json();
+}

package/dist/commands/close.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const closeCommand: Command;

package/dist/commands/close.js

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const closeCommand = new Command("close")
+    .argument("<session-id>", "Session ID")
+    .description("Close a session")
+    .option("--json", "Output JSON")
+    .action(async (sessionId, opts) => {
+    const config = requireConfig();
+    await api(config, "DELETE", `/sessions/${sessionId}`);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true }));
+    }
+    else {
+        console.log(`Closed session ${sessionId}`);
+    }
+});

package/dist/commands/create.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const createCommand: Command;

package/dist/commands/create.js

@@ -0,0 +1,18 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const createCommand = new Command("create")
+    .argument("<name>", "Session name")
+    .description("Create a new sharing session")
+    .option("--json", "Output JSON")
+    .action(async (name, opts) => {
+    const config = requireConfig();
+    const data = await api(config, "POST", "/sessions", { name });
+    if (opts.json) {
+        console.log(JSON.stringify(data));
+    }
+    else {
+        console.log(`Created session: ${data.id}`);
+        console.log(`URL: ${data.url}`);
+    }
+});

package/dist/commands/feedback.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const feedbackCommand: Command;

package/dist/commands/feedback.js

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const feedbackCommand = new Command("feedback")
+    .argument("<session-id>", "Session ID")
+    .description("Fetch feedback for a session")
+    .option("--json", "Output JSON")
+    .action(async (sessionId, opts) => {
+    const config = requireConfig();
+    const data = await api(config, "GET", `/sessions/${sessionId}/feedback`);
+    if (opts.json) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    if (data.feedback.length === 0) {
+        console.log("No feedback yet.");
+        return;
+    }
+    for (const group of data.feedback) {
+        console.log(`\n--- Version ${group.version} ---`);
+        for (const event of group.events) {
+            const who = event.viewer ?? "Anonymous";
+            console.log(`  ${who} chose "${event.choice}" — ${event.label}`);
+        }
+    }
+});

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const initCommand: Command;

package/dist/commands/init.js

@@ -0,0 +1,82 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync, cpSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const initCommand = new Command("init")
+    .description("Set up peekable — install Claude Code skill and verify connection")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    const config = requireConfig();
+    const result = { status: "ok" };
+    // 1. Test connection
+    try {
+        const res = await fetch(`${config.url}/health`);
+        if (!res.ok)
+            throw new Error("Health check failed");
+    }
+    catch {
+        const msg = `Cannot reach server at ${config.url}`;
+        if (opts.json) {
+            console.log(JSON.stringify({ status: "error", error: msg }));
+        }
+        else {
+            console.error(msg);
+        }
+        process.exit(1);
+    }
+    if (!opts.json)
+        console.log("Connection verified.");
+    // 2. Detect Claude Code and install skill
+    const claudeDir = join(homedir(), ".claude");
+    const claudeCodeDetected = existsSync(claudeDir);
+    result.claude_code = claudeCodeDetected;
+    if (claudeCodeDetected) {
+        const skillDir = join(claudeDir, "skills", "peekable");
+        // Resolve skill source relative to compiled output location
+        const skillSource = join(__dirname, "..", "..", "skill", "SKILL.md");
+        if (existsSync(skillSource)) {
+            mkdirSync(skillDir, { recursive: true });
+            cpSync(skillSource, join(skillDir, "SKILL.md"));
+            result.skill_installed = true;
+            if (!opts.json)
+                console.log("Claude Code /peekable skill installed.");
+        }
+        else {
+            result.skill_installed = false;
+            if (!opts.json)
+                console.log("Claude Code detected but skill template not found.");
+        }
+    }
+    else {
+        result.skill_installed = false;
+        if (!opts.json)
+            console.log("Claude Code not detected — skipping skill install.");
+    }
+    // 3. Test push
+    try {
+        const session = await api(config, "POST", "/sessions", { name: "__share_init_test__" });
+        await api(config, "POST", `/sessions/${session.id}/push`, {
+            html: "<html><body><p>Share init test</p></body></html>",
+        });
+        await api(config, "DELETE", `/sessions/${session.id}`);
+        result.test_push = "passed";
+        if (!opts.json)
+            console.log("Test push verified.");
+    }
+    catch (err) {
+        result.test_push = "failed";
+        result.test_error = err.message;
+        if (!opts.json)
+            console.error(`Test push failed: ${err.message}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log("\nReady to go! Try: peekable create \"My First Session\"");
+    }
+});

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const listCommand: Command;

package/dist/commands/list.js

@@ -0,0 +1,22 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const listCommand = new Command("list")
+    .description("List active sessions")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    const config = requireConfig();
+    const data = await api(config, "GET", "/sessions");
+    if (opts.json) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    if (data.sessions.length === 0) {
+        console.log("No active sessions.");
+        return;
+    }
+    console.log("Active sessions:");
+    for (const s of data.sessions) {
+        console.log(`  ${s.id}  ${s.name}  (${new Date(s.created_at).toLocaleDateString()})`);
+    }
+});

package/dist/commands/push.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const pushCommand: Command;

package/dist/commands/push.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const pushCommand = new Command("push")
+    .argument("<session-id>", "Session ID")
+    .argument("<file>", "HTML file path")
+    .description("Push an HTML file as a new version")
+    .option("--json", "Output JSON")
+    .action(async (sessionId, file, opts) => {
+    const config = requireConfig();
+    const html = readFileSync(file, "utf-8");
+    const data = await api(config, "POST", `/sessions/${sessionId}/push`, { html });
+    if (opts.json) {
+        console.log(JSON.stringify(data));
+    }
+    else {
+        console.log(`Pushed v${data.version} to ${sessionId}`);
+    }
+});

package/dist/commands/register.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const registerCommand: Command;

package/dist/commands/register.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import { writeConfig, readConfig } from "../config.js";
+import { apiNoAuth } from "../api.js";
+const DEFAULT_URL = "https://peekable.fyi";
+export const registerCommand = new Command("register")
+    .description("Register for an API key")
+    .requiredOption("--name <name>", "Your display name")
+    .requiredOption("--email <email>", "Your email address")
+    .option("--url <url>", "Server URL", DEFAULT_URL)
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    const existing = readConfig();
+    if (existing) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: "Already registered. Config exists at ~/.peekable/config.json" }));
+        }
+        else {
+            console.error("Already registered. Config exists at ~/.peekable/config.json");
+            console.error("Delete ~/.peekable/config.json to re-register.");
+        }
+        process.exit(1);
+    }
+    try {
+        const data = await apiNoAuth(opts.url, "POST", "/register", {
+            name: opts.name,
+            email: opts.email,
+        });
+        writeConfig({
+            url: opts.url,
+            api_key: data.api_key,
+            name: opts.name,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ api_key: data.api_key, url: opts.url, name: opts.name }));
+        }
+        else {
+            console.log(`Registered as ${opts.name}.`);
+            console.log(`API key saved to ~/.peekable/config.json`);
+            console.log(`\nNext step: run \`peekable init\` to complete setup.`);
+        }
+    }
+    catch (err) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: err.message }));
+        }
+        else {
+            console.error(`Registration failed: ${err.message}`);
+        }
+        process.exit(1);
+    }
+});

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface ShareConfig {
+    url: string;
+    api_key: string;
+    name: string;
+}
+export declare function readConfig(): ShareConfig | null;
+export declare function writeConfig(config: ShareConfig): void;
+export declare function requireConfig(): ShareConfig;
+export declare function getConfigPath(): string;

package/dist/config.js

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CONFIG_DIR = join(homedir(), ".peekable");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export function readConfig() {
+    if (process.env.SHARE_URL && process.env.SHARE_API_KEY) {
+        return {
+            url: process.env.SHARE_URL,
+            api_key: process.env.SHARE_API_KEY,
+            name: process.env.SHARE_NAME ?? "User",
+        };
+    }
+    if (!existsSync(CONFIG_FILE))
+        return null;
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+export function requireConfig() {
+    const config = readConfig();
+    if (!config) {
+        console.error("Not configured. Run `peekable register` first.");
+        process.exit(1);
+    }
+    return config;
+}
+export function getConfigPath() {
+    return CONFIG_FILE;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { registerCommand } from "./commands/register.js";
+import { initCommand } from "./commands/init.js";
+import { createCommand } from "./commands/create.js";
+import { pushCommand } from "./commands/push.js";
+import { feedbackCommand } from "./commands/feedback.js";
+import { listCommand } from "./commands/list.js";
+import { closeCommand } from "./commands/close.js";
+program
+    .name("peekable")
+    .description("Share HTML mockups with collaborators via peekable")
+    .version("0.1.0");
+program.addCommand(registerCommand);
+program.addCommand(initCommand);
+program.addCommand(createCommand);
+program.addCommand(pushCommand);
+program.addCommand(feedbackCommand);
+program.addCommand(listCommand);
+program.addCommand(closeCommand);
+program.parse();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "peekable",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Share HTML mockups with collaborators — CLI for peekable-server",
+  "bin": {
+    "peekable": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^12"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "tsx": "^4",
+    "@types/node": "^22"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ]
+}

package/skill/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: peekable
+description: Share HTML mockups with collaborators via public URLs. Push from Claude Code, collect structured feedback. Use when the user says "share this", "share with", "/share", "/peekable", "peekable", or wants to get a collaborator's feedback on a mockup.
+---
+
+# Peekable
+
+Share HTML mockups and playgrounds with collaborators via public URLs with structured feedback.
+
+## Commands
+
+All commands use the globally installed `peekable` CLI. Every command supports `--json` for structured output.
+
+### Share a file
+
+When the user wants to share an HTML file (playground, mockup, brainstorming companion screen):
+
+1. Create a session: `peekable create "<name>" --json`
+2. Push the HTML: `peekable push <session-id> <file-path> --json`
+3. Return the URL to the user
+
+If a session already exists for this topic, reuse it (push creates a new version, collaborators auto-reload).
+
+### Check feedback
+
+When the user asks "what did they think?" or "any feedback?":
+
+```bash
+peekable feedback <session-id> --json
+```
+
+Parse the JSON and present conversationally:
+- "Sophia chose Option B (Separate Tools) on v1"
+- "No feedback yet on v2"
+
+### List sessions
+
+```bash
+peekable list --json
+```
+
+### Close a session
+
+```bash
+peekable close <session-id> --json
+```
+
+## Behavior
+
+- Always use `--json` flag and parse the output for conversation context
+- When sharing, always give the user the full URL so they can send it to their collaborator
+- If the user says "share this" without specifying a file, look for the most recent HTML file in the current brainstorming session directory or the last playground file generated
+- Reuse existing sessions when iterating on the same topic — push creates new versions, collaborators auto-reload via WebSocket