promptdock 0.1.0

package/dist/context.js

@@ -0,0 +1,61 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { readFileSync } from "node:fs";
+/** Read the package's own version (dist/ and src/ both sit one level under the root). */
+export function readOwnVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Best-effort platform browser open (darwin `open`, win32 `start`, else xdg-open). */
+export function openUrlBestEffort(url, platform) {
+    try {
+        const [cmd, args] = platform === "darwin"
+            ? ["open", [url]]
+            : platform === "win32"
+                ? // `start` is a cmd.exe builtin; the empty "" is its window-title slot.
+                    ["cmd", ["/c", "start", "", url]]
+                : ["xdg-open", [url]];
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        /* best-effort only */
+    }
+}
+export function realContext(argv) {
+    const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    return {
+        io: {
+            out: (s) => process.stdout.write(s + "\n"),
+            err: (s) => process.stderr.write(s + "\n"),
+            write: (s) => process.stdout.write(s),
+            isTTY,
+            question: async (prompt) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    return await rl.question(prompt);
+                }
+                finally {
+                    rl.close();
+                }
+            },
+        },
+        env: process.env,
+        cwd: process.cwd(),
+        home: homedir(),
+        platform: process.platform,
+        fetch: globalThis.fetch,
+        version: readOwnVersion(),
+        argsLine: argv.join(" "),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        openUrl: (url) => openUrlBestEffort(url, process.platform),
+    };
+}

package/dist/contract.d.ts

@@ -0,0 +1,62 @@
+export type AuthStartResponse = {
+    device_code: string;
+    /** display form XXXX-XXXX */
+    user_code: string;
+    verification_url: string;
+    /** RFC-8628 minimum poll interval, secs */
+    interval: number;
+    expires_in: number;
+};
+/** Poll success (the exactly-once CAS delivery). */
+export type AuthPollToken = {
+    access_token: string;
+    token_type: "Bearer";
+    expires_at: string | null;
+};
+/** RFC-8628 verbs the poll speaks at the TOP level (the one envelope exception). */
+export type PollVerb = "authorization_pending" | "slow_down" | "access_denied" | "expired_token";
+export type WhoamiResponse = {
+    handle: string | null;
+    role: string;
+    expires_at: string | null;
+};
+export type ResolveVerdict = "ok" | "already_entitled" | "insufficient_tier" | "cap_hit" | "not_found";
+export type ResolveResponse = {
+    verdict: ResolveVerdict;
+    skill_id?: string;
+    version_id?: string;
+    version?: number;
+    title?: string;
+    author?: string;
+    is_free?: boolean;
+    file_count?: number;
+    total_bytes?: number;
+    description?: string;
+    license?: string;
+    /** insufficient_tier */
+    required?: string[];
+    current?: string;
+    /** cap_hit */
+    retry_after_secs?: number;
+};
+export type ManifestEntry = {
+    path: string;
+    bytes: number;
+    sha256: string;
+    content_type: string;
+};
+export type InstallResponse = {
+    skill: {
+        id: string;
+        slug: string;
+        title: string;
+        version: number;
+        version_id: string;
+    };
+    manifest: ManifestEntry[];
+    files: {
+        path: string;
+        url: string;
+    }[];
+    url_ttl_secs: number;
+};

package/dist/contract.js

@@ -0,0 +1,4 @@
+// Wire types for the COMMITTED server contract (app/api/v1/cli/** — Stage 3a).
+// Every field is treated as untrusted at the call sites; these types describe
+// the happy shape, they do not promise it.
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+export declare const EXIT: {
+    readonly OK: 0;
+    /** bad flags/args, non-TTY without --target/--dir, missing -y in CI */
+    readonly USAGE: 1;
+    /** not logged in / token rejected */
+    readonly AUTH: 2;
+    /** server gate: tier, cap, denial, rate limit, version floor, not found */
+    readonly DENIED: 3;
+    /** sha256 mismatch, unsafe manifest path, receipt schema problems */
+    readonly INTEGRITY: 4;
+    /** filesystem: permissions, disk, existing dir */
+    readonly IO: 5;
+    /** couldn't reach the API */
+    readonly NETWORK: 6;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** DX3: every named error footer links its docs anchor. */
+export declare function footerUrl(code: string): string;
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    /** docs anchor slug (renders the DX3 footer); omit for plain usage errors */
+    readonly footer?: string;
+    /** one-line "what to do" printed after the message */
+    readonly hint?: string;
+    constructor(message: string, exitCode: ExitCode, opts?: {
+        footer?: string;
+        hint?: string;
+    });
+}
+export declare function usageError(message: string, hint?: string): CliError;
+/**
+ * DX3 per-OS filesystem error mapping. THREE distinct messages; the --force
+ * hint belongs ONLY to the existing-dir refusal (which is not an errno — see
+ * install.ts), never to EACCES/ENOSPC (--force cannot fix those).
+ */
+export declare function mapFsError(err: unknown, path: string): CliError;
+/** DX3 network wrap (+ proxy note: Node's fetch ignores proxy env vars). */
+export declare function networkError(baseUrl: string, env: Record<string, string | undefined>): CliError;

package/dist/errors.js

@@ -0,0 +1,72 @@
+// Stable exit codes (DX3) — scripts and CI depend on these; never renumber.
+export const EXIT = {
+    OK: 0,
+    /** bad flags/args, non-TTY without --target/--dir, missing -y in CI */
+    USAGE: 1,
+    /** not logged in / token rejected */
+    AUTH: 2,
+    /** server gate: tier, cap, denial, rate limit, version floor, not found */
+    DENIED: 3,
+    /** sha256 mismatch, unsafe manifest path, receipt schema problems */
+    INTEGRITY: 4,
+    /** filesystem: permissions, disk, existing dir */
+    IO: 5,
+    /** couldn't reach the API */
+    NETWORK: 6,
+};
+/** DX3: every named error footer links its docs anchor. */
+export function footerUrl(code) {
+    return `https://promptdock.ai/docs/cli/errors#${code}`;
+}
+export class CliError extends Error {
+    exitCode;
+    /** docs anchor slug (renders the DX3 footer); omit for plain usage errors */
+    footer;
+    /** one-line "what to do" printed after the message */
+    hint;
+    constructor(message, exitCode, opts) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+        this.footer = opts?.footer;
+        this.hint = opts?.hint;
+    }
+}
+export function usageError(message, hint) {
+    return new CliError(message, EXIT.USAGE, { hint, footer: "usage" });
+}
+/**
+ * DX3 per-OS filesystem error mapping. THREE distinct messages; the --force
+ * hint belongs ONLY to the existing-dir refusal (which is not an errno — see
+ * install.ts), never to EACCES/ENOSPC (--force cannot fix those).
+ */
+export function mapFsError(err, path) {
+    const code = err?.code;
+    if (code === "EACCES" || code === "EPERM") {
+        return new CliError(`permission denied: ${path} — check permissions or choose a different --dir`, EXIT.IO, { footer: "eacces" });
+    }
+    if (code === "ENOSPC") {
+        return new CliError(`not enough disk space writing ${path} — free up space`, EXIT.IO, {
+            footer: "enospc",
+        });
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return new CliError(`filesystem error at ${path}: ${detail}`, EXIT.IO, { footer: "io" });
+}
+/** DX3 network wrap (+ proxy note: Node's fetch ignores proxy env vars). */
+export function networkError(baseUrl, env) {
+    let host = baseUrl;
+    try {
+        host = new URL(baseUrl).host;
+    }
+    catch {
+        /* keep raw */
+    }
+    const proxyVar = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"].find((k) => env[k]);
+    const proxyNote = proxyVar
+        ? ` (proxy env detected: ${proxyVar} — the CLI uses Node's built-in fetch, which does not read proxy settings)`
+        : "";
+    return new CliError(`couldn't reach ${host} — check your connection${proxyNote}`, EXIT.NETWORK, {
+        footer: "network",
+    });
+}

package/dist/generated/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const MAX_SKILL_FILES = 25;
+export declare const MAX_SKILL_TOTAL_BYTES = 5242880;
+export declare const MAX_SKILL_FILE_BYTES = 1048576;
+export declare const MAX_SKILL_IMAGES = 5;
+export declare const SKILL_REVEAL_DAILY_CAP = 15;
+export declare const CLI_MIN_VERSION = "0.1.0";
+export declare const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
+export declare const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
+export declare const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/generated/constants.js

@@ -0,0 +1,11 @@
+// GENERATED by scripts/gen-cli-constants.mjs from lib/validation/skills-constants.json
+// DO NOT EDIT — edit the JSON source and run `pnpm run gen:cli-constants`.
+export const MAX_SKILL_FILES = 25;
+export const MAX_SKILL_TOTAL_BYTES = 5242880;
+export const MAX_SKILL_FILE_BYTES = 1048576;
+export const MAX_SKILL_IMAGES = 5;
+export const SKILL_REVEAL_DAILY_CAP = 15;
+export const CLI_MIN_VERSION = "0.1.0";
+export const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
+export const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
+export const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+export declare function globalHelp(version: string): string;
+export declare const COMMAND_HELP: Record<string, string>;

package/dist/help.js

@@ -0,0 +1,84 @@
+// DX4: `promptdock --help` is a COMPLETE zero-config map; every command also
+// answers `promptdock <cmd> --help`.
+import { CANONICAL_INSTALL_COMMAND } from "./generated/constants.js";
+import { TARGETS } from "./registry.js";
+export function globalHelp(version) {
+    const targets = TARGETS.map((t) => `      ${t.id.padEnd(9)} ${t.localBase}/<slug>   (-g: ~/${t.globalBase}/<slug>)${t.experimental ? "  (experimental)" : ""}`).join("\n");
+    return `promptdock v${version} — install AI agent skills from promptdock.ai
+
+  Usage
+    ${CANONICAL_INSTALL_COMMAND} <handle>/<slug>
+
+  Commands
+    login [--token pdk_…]     log in (browser hand-off, or store a CI token)
+    logout                    remove the local token (revoke in Settings to kill it server-side)
+    whoami [--json]           show the signed-in account
+    install <ref> [options]   install a skill (ref = handle/slug, @handle/slug, or a pasted URL)
+    uninstall <ref|--all>     remove an installed skill (receipt-driven; never touches unmanaged files)
+    update [ref] [--all]      update installed skills to the latest approved version
+    upgrade                   alias of update
+    list [--json]             show installed skills (receipts)
+    help                      this map
+
+  Install options
+    -g, --global              install into the tool's per-user dir instead of the project
+    --target <tool>           skip the picker (${TARGETS.map((t) => t.id).join(", ")})
+    --dir <path>              install into an explicit directory
+    -y, --yes                 skip prompts (needs an unambiguous target; NEVER implies --force)
+    --force                   replace a non-empty foreign directory / overwrite local edits
+    --dry-run                 resolve + print what would happen; installs nothing
+    --json                    machine-readable output
+
+  Update/uninstall options
+    --check                   (update) report available updates without applying
+    --all                     operate across project-local AND global scopes
+    -g, --global              operate on the global scope (bare commands are project-local)
+
+  Targets
+${targets}
+
+  Environment
+    PROMPTDOCK_TOKEN          bearer token for CI/non-interactive use (Settings → CLI sessions → Generate token)
+    PROMPTDOCK_API_BASE       API origin override (default https://promptdock.ai)
+    NO_COLOR                  disable colored output
+
+  Exit codes
+    0 ok · 1 usage · 2 auth · 3 denied/gated · 4 integrity · 5 filesystem · 6 network
+
+  Docs: https://promptdock.ai/docs/cli`;
+}
+export const COMMAND_HELP = {
+    login: `promptdock login [--token pdk_…]
+
+Log in via the browser hand-off: the CLI prints a code, opens promptdock.ai,
+you approve there, and the terminal continues. --token stores a token minted in
+Settings → Account → CLI sessions (the CI path; or set PROMPTDOCK_TOKEN).`,
+    logout: `promptdock logout
+
+Removes the locally-stored token (~/.promptdock/config.json). The server-side
+session stays valid until revoked in Settings → Account → CLI sessions.`,
+    whoami: `promptdock whoami [--json]
+
+Shows the signed-in handle, role, and token expiry.`,
+    install: `promptdock install <handle>/<slug> [-g] [--target <tool>] [--dir <path>] [-y] [--force] [--dry-run] [--json]
+
+Installs a skill. Non-interactive sessions (CI) must pass --target or --dir
+plus -y, and authenticate via PROMPTDOCK_TOKEN. -y skips the target picker
+ONLY — a non-empty foreign directory still requires --force. --dry-run
+resolves and prints the plan without installing (and without spending any
+premium-unlock slot).`,
+    uninstall: `promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--json]
+
+Removes an installed skill using its .promptdock.json receipt — only files the
+receipt lists are ever deleted. Locally-modified files block removal without
+--force (copy your changes out first).`,
+    update: `promptdock update [<handle>/<slug>] [--all] [--check] [-g] [-y] [--force] [--json]
+
+Updates installed skills to the latest approved version. Bare \`update\` covers
+the project-local scope; -g the global scope; --all both. --check reports
+without applying. Locally-modified files block an update without --force.`,
+    list: `promptdock list [--json] [-g] [--all]
+
+Lists installed skills from their receipts: ref, version, target, installed-at.`,
+    help: `promptdock help — prints the global command map.`,
+};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// promptdock — the PromptDock skills CLI (Stage 3b).
+// Contract: app/api/v1/cli/** (server), docs/plans/skills-marketplace.md.
+import { parseArgs } from "./args.js";
+import { realContext } from "./context.js";
+import { CliError, EXIT, footerUrl } from "./errors.js";
+import { COMMAND_HELP, globalHelp } from "./help.js";
+import { colors } from "./ui.js";
+import { runInstall } from "./commands/install.js";
+import { runLogin, runLogout, runWhoami } from "./commands/login.js";
+import { runList, runUninstall, runUpdate } from "./commands/lifecycle.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    const ctx = realContext(argv);
+    const c = colors(ctx.env, Boolean(process.stderr.isTTY));
+    try {
+        const { command, positionals, flags } = parseArgs(argv);
+        if (command === "version") {
+            ctx.io.out(ctx.version);
+            return EXIT.OK;
+        }
+        if (command === "help" || command === null) {
+            ctx.io.out(globalHelp(ctx.version));
+            return EXIT.OK;
+        }
+        if (flags.help === true) {
+            ctx.io.out(COMMAND_HELP[command] ?? globalHelp(ctx.version));
+            return EXIT.OK;
+        }
+        switch (command) {
+            case "login":
+                await runLogin(ctx, flags);
+                return EXIT.OK;
+            case "logout":
+                await runLogout(ctx);
+                return EXIT.OK;
+            case "whoami":
+                await runWhoami(ctx, flags);
+                return EXIT.OK;
+            case "install":
+                await runInstall(ctx, positionals, flags);
+                return EXIT.OK;
+            case "uninstall":
+                await runUninstall(ctx, positionals, flags);
+                return EXIT.OK;
+            case "update":
+                await runUpdate(ctx, positionals, flags);
+                return EXIT.OK;
+            case "list":
+                await runList(ctx, flags);
+                return EXIT.OK;
+            default:
+                ctx.io.err(`unknown command "${command}" — run: promptdock --help`);
+                return EXIT.USAGE;
+        }
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            ctx.io.err(c.red(err.message));
+            if (err.hint)
+                ctx.io.err(err.hint);
+            if (err.footer)
+                ctx.io.err(c.dim(footerUrl(err.footer)));
+            return err.exitCode;
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        ctx.io.err(c.red(`unexpected error: ${detail}`));
+        ctx.io.err(c.dim(footerUrl("internal")));
+        return EXIT.USAGE;
+    }
+}
+main().then((code) => process.exit(code), () => process.exit(EXIT.USAGE));

package/dist/installer.d.ts

@@ -0,0 +1,43 @@
+import type { Api } from "./api.js";
+import type { CliContext } from "./context.js";
+import type { InstallResponse, ManifestEntry } from "./contract.js";
+import { type Receipt } from "./receipts.js";
+/** Narrow the untrusted install response; throws INTEGRITY on a bad shape. */
+export declare function checkInstallResponse(resp: unknown): InstallResponse;
+/**
+ * E8 client-side re-validation + the shared D7 bounds. A server compromise must
+ * not become an arbitrary file write OR a disk-filling download.
+ */
+export declare function assertSafeManifest(manifest: ManifestEntry[]): void;
+export type StagedInstall = {
+    tempDir: string;
+    files: {
+        path: string;
+        sha256: string;
+    }[];
+};
+/**
+ * Download every manifest file into `<parent>/.promptdock-staging-*` (SIBLING of
+ * the target so the final rename never crosses filesystems), verifying sha256 +
+ * byte length against the manifest. Throws (and discards the temp dir) on ANY
+ * mismatch — the sha in the manifest is the transport-integrity anchor.
+ */
+export declare function downloadAndStage(ctx: CliContext, api: Api, resp: InstallResponse, targetDir: string): Promise<StagedInstall>;
+/**
+ * Atomic-ish commit: fresh target → one rename; existing target → staged
+ * replace (target → .promptdock-old-*, temp → target, drop old; on failure the
+ * old dir is restored). Same-parent renames only.
+ */
+export declare function commitStaged(tempDir: string, targetDir: string): void;
+/**
+ * The full phase-2: download → verify → commit → receipt → best-effort complete.
+ * `refString` is the canonical handle/slug; `prior` carries a matching update's
+ * receipt so unknown fields survive the rewrite (DX F16).
+ */
+export declare function performInstall(ctx: CliContext, api: Api, opts: {
+    resp: InstallResponse;
+    targetDir: string;
+    targetId: string;
+    refString: string;
+    prior?: Receipt;
+}): Promise<Receipt>;