promptdock 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# promptdock
+
+Install AI agent **skills** from [PromptDock](https://promptdock.ai) into Claude Code,
+Codex, Gemini CLI, Cursor, GitHub Copilot, and more.
+
+```bash
+npx promptdock@latest install <handle>/<slug>
+```
+
+## 60-second quickstart
+
+```bash
+# 1) Install a skill into this project (the CLI walks you through login + target)
+npx promptdock@latest install garry/seo-content-audit
+
+# 2) Approve the login code in your browser when prompted (one time per machine)
+
+# 3) Start a NEW session in Claude Code and type /seo-content-audit
+```
+
+**Auth model, stated plainly: login is required.** A free PromptDock account
+installs free skills — no card, no subscription. Premium skills need the
+Explorer plan ($10/mo) or higher. `login` opens your browser; you approve a
+one-time code and the terminal continues. The token lives in
+`~/.promptdock/config.json` (owner-only permissions; on Windows the user
+profile's ACL is the boundary).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `login [--token pdk_…]` | Browser hand-off login, or store a CI token from Settings → CLI sessions |
+| `logout` | Remove the local token (revoke in Settings to kill the session server-side) |
+| `whoami [--json]` | Show the signed-in account + token expiry |
+| `install <ref> [options]` | Install a skill (`ref` = `handle/slug`, `@handle/slug`, or a pasted URL) |
+| `uninstall <ref \| --all>` | Remove an installed skill (receipt-driven — see below) |
+| `update [ref] [--all] [--check]` | Update to the latest approved version (`upgrade` is an alias) |
+| `list [--json] [-g] [--all]` | Show installed skills |
+
+Install options: `-g/--global` (per-user dir), `--target <tool>`, `--dir <path>`,
+`-y/--yes` (skip prompts — **never** implies `--force`), `--force`, `--dry-run`
+(print the plan, install nothing), `--json`.
+
+## Install targets
+
+| Target | Project install | Global (`-g`) | Status |
+| --- | --- | --- | --- |
+| `claude` (Claude Code) | `.claude/skills/<slug>/` | `~/.claude/skills/<slug>/` | supported |
+| `codex` | `.codex/skills/<slug>/` | `~/.codex/skills/<slug>/` | experimental |
+| `gemini` (Gemini CLI) | `.gemini/skills/<slug>/` | `~/.gemini/skills/<slug>/` | experimental |
+| `cursor` | `.cursor/skills/<slug>/` | `~/.cursor/skills/<slug>/` | experimental |
+| `copilot` (GitHub Copilot) | `.github/skills/<slug>/` | `~/.copilot/skills/<slug>/` | experimental |
+| `kimi` | `.kimi/skills/<slug>/` | `~/.kimi/skills/<slug>/` | experimental |
+| `openai` (OpenAI/GPT) | `.openai/skills/<slug>/` | `~/.openai/skills/<slug>/` | experimental |
+
+Tools detected in your project (or home dir with `-g`) float to the top of the
+picker and are preselected. `--dir <path>` installs anywhere. After installing,
+**restart/reopen the tool** — most agents only scan skills at session start
+(Claude Code: start a *new* session, then type `/<slug>`).
+
+## CI / non-interactive use
+
+Non-TTY sessions never open a browser or show a picker. The contract:
+
+```bash
+export PROMPTDOCK_TOKEN=pdk_…       # Settings → Account → CLI sessions → Generate token
+npx promptdock@latest install garry/seo-content-audit --target claude -y
+```
+
+- `PROMPTDOCK_TOKEN` — bearer token (overrides any stored login).
+- `PROMPTDOCK_API_BASE` — API origin override (default `https://promptdock.ai`).
+- Without `--target`/`--dir` **and** `-y`, a non-interactive install exits `1`
+  with the exact flags to add. Without a token it exits `2`.
+- `NO_COLOR` is honored.
+
+## Receipts, update, uninstall
+
+Every install writes `<dir>/.promptdock.json` — the **receipt** (`schema: 1`):
+skill id, ref, version, and the sha256 of every installed file. It is the
+*only* authority the CLI trusts for later operations:
+
+- `update` re-resolves each receipt and reinstalls when a newer approved
+  version exists (`--check` reports without applying). Bare `update` covers the
+  project; `-g` the global scope; `--all` both.
+- `uninstall` removes **only** files the receipt lists, then the receipt, then
+  any emptied directories. Files you added are never touched.
+- If you **edited** installed files, update/uninstall refuse without `--force`
+  ("copy your changes out first") — your local changes never die to a default.
+- A receipt written by a newer CLI version is left alone with a
+  "run `npx promptdock@latest`" notice — never a guessy uninstall.
+
+Downloads are verified against the server manifest (per-file sha256) and every
+path is re-validated before any write; a failed check aborts **all-or-nothing**
+("integrity check failed — nothing installed").
+
+## Exit codes & errors
+
+| Code | Meaning |
+| --- | --- |
+| 0 | success |
+| 1 | usage (bad flags, missing `--target`/`-y` in CI) |
+| 2 | auth (not logged in / token rejected) |
+| 3 | denied (tier gate, daily cap, denial, rate limit, version floor, not found) |
+| 4 | integrity (sha mismatch, unsafe manifest path, receipt schema) |
+| 5 | filesystem (permissions, disk space, non-empty directory) |
+| 6 | network |
+
+Every named error links `https://promptdock.ai/docs/cli/errors#<code>`.
+
+## Notes
+
+- Node.js ≥ 18. Zero runtime dependencies.
+- The CLI always installs the **latest approved** version of a skill (no semver
+  pinning); every published skill has passed PromptDock's human review queue.
+  Review is a screening step, not a warranty — read what you install.
+- Skills are plain files on your machine after install; premium gates access,
+  not copying.

package/dist/api.d.ts

@@ -0,0 +1,25 @@
+import type { CliContext } from "./context.js";
+export type ApiEnvelopeError = {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type RawResponse = {
+    status: number;
+    body: unknown;
+    headers: Headers;
+};
+export declare class Api {
+    private readonly ctx;
+    readonly baseUrl: string;
+    private readonly token;
+    constructor(ctx: CliContext, baseUrl: string, token: string | null);
+    private headers;
+    /** Network-wrapped fetch; parses JSON (null body on parse failure). Never throws on HTTP status. */
+    raw(method: string, path: string, body?: unknown): Promise<RawResponse>;
+    /** Envelope-aware request: 2xx → typed body; anything else → a mapped CliError. */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Extract {error:{code,message,details}} defensively (untrusted input). */
+    static envelope(body: unknown): ApiEnvelopeError | null;
+    private mapEnvelopeError;
+}

package/dist/api.js

@@ -0,0 +1,100 @@
+import { CliError, EXIT, networkError } from "./errors.js";
+export class Api {
+    ctx;
+    baseUrl;
+    token;
+    constructor(ctx, baseUrl, token) {
+        this.ctx = ctx;
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    headers(hasBody) {
+        const h = {
+            "user-agent": `promptdock-cli/${this.ctx.version}`,
+            "x-promptdock-cli-version": this.ctx.version,
+            "x-promptdock-cli-args": this.ctx.argsLine.slice(0, 120),
+            accept: "application/json",
+        };
+        if (hasBody)
+            h["content-type"] = "application/json";
+        if (this.token)
+            h.authorization = `Bearer ${this.token}`;
+        return h;
+    }
+    /** Network-wrapped fetch; parses JSON (null body on parse failure). Never throws on HTTP status. */
+    async raw(method, path, body) {
+        let res;
+        try {
+            res = await this.ctx.fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: this.headers(body !== undefined),
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch {
+            throw networkError(this.baseUrl, this.ctx.env);
+        }
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            /* non-JSON body (should not happen on /api/v1) */
+        }
+        return { status: res.status, body: parsed, headers: res.headers };
+    }
+    /** Envelope-aware request: 2xx → typed body; anything else → a mapped CliError. */
+    async request(method, path, body) {
+        const res = await this.raw(method, path, body);
+        if (res.status >= 200 && res.status < 300)
+            return res.body;
+        throw this.mapEnvelopeError(res);
+    }
+    /** Extract {error:{code,message,details}} defensively (untrusted input). */
+    static envelope(body) {
+        if (typeof body !== "object" || body === null)
+            return null;
+        const err = body.error;
+        if (typeof err !== "object" || err === null)
+            return null;
+        const e = err;
+        if (typeof e.code !== "string")
+            return null;
+        return {
+            code: e.code,
+            message: typeof e.message === "string" ? e.message : e.code,
+            details: typeof e.details === "object" && e.details !== null
+                ? e.details
+                : undefined,
+        };
+    }
+    mapEnvelopeError(res) {
+        const env = Api.envelope(res.body);
+        // 426 version floor: print the SERVER's remedy verbatim (DX3/F8) — the
+        // server knows the canonical command better than a stale client does.
+        if (res.status === 426) {
+            const remedy = typeof env?.details?.remedy === "string" ? env.details.remedy : null;
+            const msg = env?.message ?? "This promptdock CLI version is no longer supported.";
+            return new CliError(remedy ? `${msg}\n${remedy}` : msg, EXIT.DENIED, {
+                footer: "upgrade_required",
+            });
+        }
+        if (res.status === 401) {
+            return new CliError(env?.message ?? "Not authenticated.", EXIT.AUTH, {
+                footer: "auth",
+                hint: "run: npx promptdock@latest login",
+            });
+        }
+        if (res.status === 429) {
+            const retryAfter = res.headers.get("retry-after");
+            const secs = retryAfter ? Number(retryAfter) : null;
+            const wait = secs && Number.isFinite(secs) ? ` Retry in ~${Math.ceil(secs / 60)} min.` : "";
+            return new CliError((env?.message ?? "Rate limited.") + wait, EXIT.DENIED, {
+                footer: env?.code ?? "rate_limited",
+            });
+        }
+        return new CliError(env?.message ?? `request failed (HTTP ${res.status})`, EXIT.DENIED, {
+            footer: env?.code ?? "api",
+        });
+    }
+}

package/dist/args.d.ts

@@ -0,0 +1,18 @@
+export type ParsedArgs = {
+    command: string | null;
+    positionals: string[];
+    flags: Record<string, string | boolean>;
+};
+export type FlagSpec = {
+    /** flags that take NO value (presence = true) */
+    booleans: string[];
+    /** flags that REQUIRE a value (`--flag value` or `--flag=value`) */
+    values: string[];
+    /** short → long aliases (e.g. g → global, y → yes) */
+    aliases?: Record<string, string>;
+};
+export declare const GLOBAL_ALIASES: Record<string, string>;
+export declare const COMMAND_SPECS: Record<string, FlagSpec>;
+/** `upgrade` aliases `update` (DX2 npm muscle memory). */
+export declare const COMMAND_ALIASES: Record<string, string>;
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/args.js

@@ -0,0 +1,103 @@
+// Hand-rolled arg parser (zero-dep bias). Spec-driven: each command declares its
+// boolean flags and value-taking flags; unknown flags are a usage error (exit 1).
+import { usageError } from "./errors.js";
+export const GLOBAL_ALIASES = {
+    g: "global",
+    y: "yes",
+    h: "help",
+    v: "version",
+};
+export const COMMAND_SPECS = {
+    login: { booleans: ["help"], values: ["token"] },
+    logout: { booleans: ["help"], values: [] },
+    whoami: { booleans: ["help", "json"], values: [] },
+    install: {
+        booleans: ["help", "json", "global", "yes", "force", "dry-run"],
+        values: ["target", "dir"],
+    },
+    uninstall: {
+        booleans: ["help", "json", "global", "yes", "force", "all"],
+        values: ["target", "dir"],
+    },
+    update: {
+        booleans: ["help", "json", "global", "yes", "force", "all", "check"],
+        values: ["target", "dir"],
+    },
+    list: { booleans: ["help", "json", "global", "all"], values: [] },
+    help: { booleans: [], values: [] },
+};
+/** `upgrade` aliases `update` (DX2 npm muscle memory). */
+export const COMMAND_ALIASES = { upgrade: "update" };
+export function parseArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    let command = null;
+    // Global, command-less forms first.
+    const first = argv[0];
+    if (first === "--version" || first === "-v")
+        return { command: "version", positionals: [], flags: {} };
+    if (first === "--help" || first === "-h" || first === undefined) {
+        return { command: "help", positionals: [], flags: {} };
+    }
+    if (first.startsWith("-"))
+        throw usageError(`unknown option "${first}"`, "run: promptdock --help");
+    command = COMMAND_ALIASES[first] ?? first;
+    const spec = COMMAND_SPECS[command];
+    if (!spec) {
+        throw usageError(`unknown command "${first}"`, "run: promptdock --help");
+    }
+    const canon = (name) => spec.aliases?.[name] ?? GLOBAL_ALIASES[name] ?? name;
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--") {
+            positionals.push(...rest.slice(i + 1));
+            break;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            const name = canon(eq === -1 ? a.slice(2) : a.slice(2, eq));
+            if (spec.booleans.includes(name)) {
+                if (eq !== -1)
+                    throw usageError(`--${name} takes no value`);
+                flags[name] = true;
+            }
+            else if (spec.values.includes(name)) {
+                const value = eq !== -1 ? a.slice(eq + 1) : rest[++i];
+                if (value === undefined || (eq === -1 && value.startsWith("-"))) {
+                    throw usageError(`--${name} requires a value`);
+                }
+                flags[name] = value;
+            }
+            else {
+                throw usageError(`unknown option "--${name}" for ${command}`, `run: promptdock ${command} --help`);
+            }
+        }
+        else if (a.startsWith("-") && a.length > 1) {
+            // Short flags; bundles allowed for booleans (-gy). A value-taking short
+            // flag must be last in the bundle.
+            const chars = a.slice(1).split("");
+            for (let c = 0; c < chars.length; c++) {
+                const name = canon(chars[c]);
+                if (spec.booleans.includes(name)) {
+                    flags[name] = true;
+                }
+                else if (spec.values.includes(name)) {
+                    if (c !== chars.length - 1)
+                        throw usageError(`-${chars[c]} requires a value`);
+                    const value = rest[++i];
+                    if (value === undefined || value.startsWith("-"))
+                        throw usageError(`-${chars[c]} requires a value`);
+                    flags[name] = value;
+                }
+                else {
+                    throw usageError(`unknown option "-${chars[c]}" for ${command}`, `run: promptdock ${command} --help`);
+                }
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { command, positionals, flags };
+}

package/dist/auth.d.ts

@@ -0,0 +1,20 @@
+import { Api } from "./api.js";
+import type { CliContext } from "./context.js";
+/**
+ * Run the browser hand-off and return the bearer token. NEVER logs the token.
+ * DX1: a code that expires while waiting AUTO-RESTARTS the flow ONCE (new code,
+ * reprint, keep waiting); a second expiry is the honest timeout.
+ */
+export declare function deviceFlowLogin(ctx: CliContext, baseUrl: string, opts: {
+    long: boolean;
+}): Promise<string>;
+/**
+ * Resolve auth for a token-authed command. Env PROMPTDOCK_TOKEN first (CI),
+ * then the stored config; no token + TTY → inline device-flow login with the
+ * DX1 LONG (15-min) code (this is the "start follows a login_required verdict"
+ * path — a fresh signup races email confirmation); no token + non-TTY → exit 2.
+ */
+export declare function ensureAuth(ctx: CliContext): Promise<{
+    api: Api;
+    baseUrl: string;
+}>;

package/dist/auth.js

@@ -0,0 +1,135 @@
+// Device-flow login (RFC-8628 client half) + the shared "make sure we hold a
+// token" helper. The poll family speaks RFC verbs at the TOP level of the body
+// (the one envelope exception) — so it rides Api.raw, never Api.request.
+import { hostname } from "node:os";
+import { Api } from "./api.js";
+import { loadConfig, resolveApiBase, resolveToken, saveConfig } from "./config.js";
+import { CliError, EXIT } from "./errors.js";
+import { formatCountdown } from "./ui.js";
+/**
+ * Run the browser hand-off and return the bearer token. NEVER logs the token.
+ * DX1: a code that expires while waiting AUTO-RESTARTS the flow ONCE (new code,
+ * reprint, keep waiting); a second expiry is the honest timeout.
+ */
+export async function deviceFlowLogin(ctx, baseUrl, opts) {
+    const api = new Api(ctx, baseUrl, null);
+    let restarts = 0;
+    for (;;) {
+        const start = await api.request("POST", "/api/v1/cli/auth/start", {
+            device_label: safeDeviceLabel(),
+            long: opts.long,
+        });
+        ctx.io.out("");
+        ctx.io.out("Confirm this code in your browser:");
+        ctx.io.out("");
+        ctx.io.out(`    ${start.user_code}`);
+        ctx.io.out("");
+        ctx.io.out(`Open: ${start.verification_url}`);
+        if (ctx.io.isTTY) {
+            ctx.openUrl(start.verification_url);
+            ctx.io.out("(if the page didn't open, paste the URL into your browser)");
+        }
+        ctx.io.out("");
+        const deadline = ctx.now() + Math.max(1, start.expires_in) * 1000;
+        let intervalSecs = Math.max(0, Number(start.interval) || 0);
+        poll: for (;;) {
+            if (ctx.now() >= deadline)
+                break poll; // local expiry — restart below
+            await waitWithCountdown(ctx, intervalSecs, deadline);
+            const res = await api.raw("POST", "/api/v1/cli/auth/poll", {
+                device_code: start.device_code,
+            });
+            if (res.status >= 200 && res.status < 300) {
+                const body = res.body;
+                if (body && typeof body.access_token === "string") {
+                    clearCountdown(ctx);
+                    return body.access_token;
+                }
+                break poll; // malformed success — treat as expired, restart once
+            }
+            const verb = pollVerb(res.body);
+            if (verb === "authorization_pending")
+                continue;
+            if (verb === "slow_down") {
+                const retryAfter = Number(res.headers.get("retry-after"));
+                intervalSecs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : intervalSecs + 5;
+                continue;
+            }
+            clearCountdown(ctx);
+            if (verb === "access_denied") {
+                throw new CliError("Login was denied from the browser.", EXIT.DENIED, {
+                    footer: "access_denied",
+                });
+            }
+            break poll; // expired_token (or unknown) — restart below
+        }
+        clearCountdown(ctx);
+        restarts += 1;
+        if (restarts > 1) {
+            throw new CliError("login timed out — run `npx promptdock@latest login` to retry", EXIT.AUTH, {
+                footer: "login_timeout",
+            });
+        }
+        ctx.io.out("That code expired — starting a fresh one…");
+        opts = { long: true };
+    }
+}
+/**
+ * Resolve auth for a token-authed command. Env PROMPTDOCK_TOKEN first (CI),
+ * then the stored config; no token + TTY → inline device-flow login with the
+ * DX1 LONG (15-min) code (this is the "start follows a login_required verdict"
+ * path — a fresh signup races email confirmation); no token + non-TTY → exit 2.
+ */
+export async function ensureAuth(ctx) {
+    const config = loadConfig(ctx.home);
+    const baseUrl = resolveApiBase(ctx.env, config);
+    let token = resolveToken(ctx.env, config);
+    if (!token) {
+        if (!ctx.io.isTTY) {
+            throw new CliError("not logged in — set the PROMPTDOCK_TOKEN environment variable, or run `npx promptdock@latest login` interactively", EXIT.AUTH, { footer: "auth" });
+        }
+        ctx.io.out("You need to log in first.");
+        token = await deviceFlowLogin(ctx, baseUrl, { long: true });
+        saveConfig(ctx.home, { ...config, token, api_base: baseUrl }, ctx.platform);
+        ctx.io.out("✓ Logged in.");
+    }
+    return { api: new Api(ctx, baseUrl, token), baseUrl };
+}
+function pollVerb(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const v = body.error;
+    return v === "authorization_pending" || v === "slow_down" || v === "access_denied" || v === "expired_token"
+        ? v
+        : null;
+}
+/** Live countdown (TTY repaint; non-TTY just sleeps — no log spam in CI). */
+async function waitWithCountdown(ctx, secs, deadlineMs) {
+    const end = Math.min(ctx.now() + secs * 1000, deadlineMs);
+    if (!ctx.io.isTTY) {
+        const ms = end - ctx.now();
+        if (ms > 0)
+            await ctx.sleep(ms);
+        return;
+    }
+    for (;;) {
+        const remainMs = end - ctx.now();
+        const left = Math.max(0, Math.round((deadlineMs - ctx.now()) / 1000));
+        ctx.io.write(`\rWaiting for approval… ${formatCountdown(left)}  `);
+        if (remainMs <= 0)
+            return;
+        await ctx.sleep(Math.min(1000, remainMs));
+    }
+}
+function clearCountdown(ctx) {
+    if (ctx.io.isTTY)
+        ctx.io.write("\r\u001b[2K");
+}
+function safeDeviceLabel() {
+    try {
+        return hostname().slice(0, 64) || "promptdock-cli";
+    }
+    catch {
+        return "promptdock-cli";
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import type { CliContext } from "../context.js";
+export declare function runInstall(ctx: CliContext, positionals: string[], flags: Record<string, string | boolean>): Promise<void>;