promptdock 0.1.0

package/dist/commands/install.js

@@ -0,0 +1,210 @@
+// `promptdock install <ref>` — resolve → verdict → target → confirm → two-phase
+// install. D-UX11 contracts: non-TTY needs --target/--dir (+ -y); -y skips the
+// PICKER only, never --force; --dry-run is PURE (resolve only — the E5 mint
+// happens at POST install, which dry-run never calls).
+import { existsSync, readdirSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { ensureAuth } from "../auth.js";
+import { CliError, EXIT, usageError } from "../errors.js";
+import { checkInstallResponse, performInstall } from "../installer.js";
+import { formatRef, parseSkillRef } from "../ref.js";
+import { detectTargets, nextStepLine, targetById, targetInstallDir, TARGETS, } from "../registry.js";
+import { readReceipt } from "../receipts.js";
+import { colors, confirm, formatBytes, promptSelect } from "../ui.js";
+import { assertInstallable } from "../verdicts.js";
+const NON_TTY_TARGET_HINT = "no install target in a non-interactive session — pass --target <tool> or --dir <path> (e.g. --target claude), plus -y to confirm";
+export async function runInstall(ctx, positionals, flags) {
+    const refInput = positionals[0];
+    if (!refInput)
+        throw usageError("missing skill ref", "usage: promptdock install <handle>/<slug>");
+    const ref = parseSkillRef(refInput);
+    if (!ref) {
+        throw usageError(`"${refInput}" isn't a valid skill ref`, "expected handle/slug (a pasted promptdock.ai skill URL also works)");
+    }
+    const refString = formatRef(ref);
+    const json = flags.json === true;
+    const dryRun = flags["dry-run"] === true;
+    const c = colors(ctx.env, ctx.io.isTTY);
+    const { api } = await ensureAuth(ctx);
+    const resolve = await api.request("GET", `/api/v1/cli/skills/resolve?ref=${encodeURIComponent(refString)}`);
+    assertInstallable(resolve, refString);
+    if (typeof resolve.version_id !== "string" || typeof resolve.skill_id !== "string") {
+        throw new CliError("malformed resolve response — update the CLI and retry", EXIT.DENIED, {
+            footer: "verdict",
+        });
+    }
+    // ── target resolution (D-UX11) ─────────────────────────────────────────────
+    const picked = await resolveTarget(ctx, flags, ref);
+    // ── receipt awareness (DX3/DX5) ────────────────────────────────────────────
+    const existing = readReceipt(picked.dir);
+    if (existing.kind === "newer_schema") {
+        throw new CliError(`${picked.dir} was installed by a newer promptdock CLI (receipt schema ${existing.schema}). Run: npx promptdock@latest ${ctx.argsLine}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
+    }
+    const matching = existing.kind === "ok" && existing.receipt.skill_id === resolve.skill_id
+        ? existing.receipt
+        : null;
+    const isUpdate = matching !== null;
+    if (!isUpdate && !dryRun && flags.force !== true && dirIsNonEmpty(picked.dir)) {
+        // The ONLY error whose remedy is --force (DX3).
+        const what = existing.kind === "ok" ? `a different skill (${existing.receipt.ref})` : "files";
+        throw new CliError(`${picked.dir} already exists and contains ${what} — pass --force to replace it`, EXIT.IO, { footer: "existing_dir" });
+    }
+    if (isUpdate && matching.version_id === resolve.version_id && flags.force !== true && !dryRun) {
+        ctx.io.out(json
+            ? JSON.stringify({ installed: false, up_to_date: true, version: matching.version, path: picked.dir })
+            : `"${resolve.title ?? refString}" is already up to date (v${matching.version}) at ${picked.dir} — use --force to reinstall.`);
+        return;
+    }
+    // ── summary block (D-UX11 confirm-before-write) ────────────────────────────
+    const summary = [];
+    if (isUpdate) {
+        summary.push(`Update ${c.bold(`"${resolve.title ?? refString}"`)} by @${resolve.author ?? ref.handle}`);
+        summary.push(`  version:  v${matching.version} → v${resolve.version}`);
+    }
+    else {
+        summary.push(`Install ${c.bold(`"${resolve.title ?? refString}"`)} by @${resolve.author ?? ref.handle}`);
+        summary.push(`  version:  v${resolve.version}`);
+    }
+    summary.push(`  files:    ${resolve.file_count ?? "?"} files · ${formatBytes(Number(resolve.total_bytes) || 0)}`);
+    if (resolve.license)
+        summary.push(`  license:  ${resolve.license}`);
+    summary.push(`  access:   ${resolve.is_free === false ? "premium" : "free"}`);
+    summary.push(`  to:       ${picked.dir}`);
+    if (dryRun) {
+        if (json) {
+            ctx.io.out(JSON.stringify({
+                dry_run: true,
+                ref: refString,
+                skill_id: resolve.skill_id,
+                version_id: resolve.version_id,
+                version: resolve.version,
+                title: resolve.title ?? null,
+                author: resolve.author ?? null,
+                is_free: resolve.is_free ?? null,
+                file_count: resolve.file_count ?? null,
+                total_bytes: resolve.total_bytes ?? null,
+                target: picked.id,
+                path: picked.dir,
+                update: isUpdate,
+            }));
+            return;
+        }
+        for (const line of summary)
+            ctx.io.out(line);
+        ctx.io.out("");
+        ctx.io.out(c.dim("Dry run — nothing was installed (the file list is fetched and verified at install)."));
+        return;
+    }
+    // Confirm: -y skips; TTY prompts; non-TTY without -y refuses (D-UX11).
+    if (flags.yes !== true) {
+        if (!ctx.io.isTTY) {
+            throw usageError("confirmation needed in a non-interactive session", "re-run with -y");
+        }
+        for (const line of summary)
+            ctx.io.out(line);
+        const go = await confirm(ctx.io, isUpdate ? "Update?" : "Install?", true);
+        if (!go) {
+            ctx.io.out("Cancelled — nothing installed.");
+            return;
+        }
+    }
+    // ── two-phase install ──────────────────────────────────────────────────────
+    const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolve.skill_id}/install`, { version_id: resolve.version_id });
+    const resp = checkInstallResponse(respRaw);
+    if (!json) {
+        ctx.io.out(`Downloading ${resp.manifest.length} files…`);
+        const shown = resp.manifest.slice(0, 8);
+        for (const e of shown)
+            ctx.io.out(`  ${e.path} ${c.dim(`(${formatBytes(e.bytes)})`)}`);
+        if (resp.manifest.length > shown.length) {
+            ctx.io.out(c.dim(`  +${resp.manifest.length - shown.length} more`));
+        }
+    }
+    const receipt = await performInstall(ctx, api, {
+        resp,
+        targetDir: picked.dir,
+        targetId: picked.id,
+        refString,
+        prior: matching ?? undefined,
+    });
+    if (json) {
+        ctx.io.out(JSON.stringify({
+            installed: true,
+            update: isUpdate,
+            ref: refString,
+            version: receipt.version,
+            version_id: receipt.version_id,
+            target: picked.id,
+            path: picked.dir,
+            files: receipt.files.length,
+        }));
+        return;
+    }
+    ctx.io.out("");
+    ctx.io.out(`${c.green("✓")} ${isUpdate ? "Updated" : "Installed"} "${resp.skill.title}" v${resp.skill.version} → ${picked.dir}`);
+    ctx.io.out(nextStepLine(picked.id, resp.skill.slug));
+}
+async function resolveTarget(ctx, flags, ref) {
+    const global = flags.global === true;
+    if (typeof flags.dir === "string") {
+        const dir = isAbsolute(flags.dir) ? flags.dir : resolvePath(ctx.cwd, flags.dir);
+        return { id: "custom", dir };
+    }
+    if (typeof flags.target === "string") {
+        const def = targetById(flags.target);
+        if (!def) {
+            throw usageError(`unknown --target "${flags.target}"`, `known targets: ${TARGETS.map((t) => t.id).join(", ")} (or use --dir <path>)`);
+        }
+        return {
+            id: def.id,
+            dir: targetInstallDir(def, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug }),
+        };
+    }
+    const detected = detectTargets({ cwd: ctx.cwd, home: ctx.home, global });
+    if (!ctx.io.isTTY)
+        throw usageError(NON_TTY_TARGET_HINT);
+    if (flags.yes === true) {
+        // -y skips the PICKER only, and only when detection is unambiguous (D-UX11).
+        const found = detected.filter((t) => t.detected);
+        if (found.length === 1) {
+            return {
+                id: found[0].id,
+                dir: targetInstallDir(found[0], { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug }),
+            };
+        }
+        throw usageError(found.length === 0
+            ? "-y needs a detectable target and none was found — pass --target <tool> or --dir <path>"
+            : `-y needs an unambiguous target and ${found.length} tools were detected — pass --target <tool> or --dir <path>`);
+    }
+    const scopeNote = global ? " (global)" : "";
+    const options = detected.map((t) => {
+        const dir = targetInstallDir(t, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug });
+        const tags = [t.detected ? "(detected)" : null, t.experimental ? "(experimental)" : null]
+            .filter(Boolean)
+            .join(" ");
+        return `${t.label.padEnd(16)} ${dir}${tags ? `  ${tags}` : ""}`;
+    });
+    options.push("Custom path…      (type any directory)");
+    const idx = await promptSelect(ctx.io, `Where should this skill be installed?${scopeNote}`, options, 0);
+    if (idx === options.length - 1) {
+        const answer = (await ctx.io.question("Directory: ")).trim();
+        if (!answer)
+            throw usageError("no directory given");
+        return { id: "custom", dir: isAbsolute(answer) ? answer : resolvePath(ctx.cwd, answer) };
+    }
+    const chosen = detected[idx];
+    return {
+        id: chosen.id,
+        dir: targetInstallDir(chosen, { cwd: ctx.cwd, home: ctx.home, global, slug: ref.slug }),
+    };
+}
+function dirIsNonEmpty(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        return true; // unreadable = treat as occupied (never clobber blind)
+    }
+}

package/dist/commands/lifecycle.d.ts

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

package/dist/commands/lifecycle.js

@@ -0,0 +1,257 @@
+// `uninstall` / `update` / `list` — the receipt-driven local lifecycle (U2).
+// The receipt is the ONLY authority: the CLI never deletes a file no receipt
+// lists, and a modified file blocks destructive ops without --force (DX5).
+import { existsSync, lstatSync, rmdirSync, rmSync, unlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { ensureAuth } from "../auth.js";
+import { CliError, EXIT, mapFsError, usageError } from "../errors.js";
+import { checkInstallResponse, performInstall } from "../installer.js";
+import { formatRef, parseSkillRef } from "../ref.js";
+import { modifiedFiles, readReceipt, scanReceipts, RECEIPT_NAME, } from "../receipts.js";
+import { colors, confirm } from "../ui.js";
+import { assertInstallable } from "../verdicts.js";
+/** U2/DX2 scope rules: bare = project-local; -g = global; --all = both. */
+function scopeOf(flags) {
+    if (flags.all === true)
+        return "both";
+    return flags.global === true ? "global" : "local";
+}
+function newerSchemaError(dir, schema, argsLine) {
+    return new CliError(`${dir} was installed by a newer promptdock CLI (receipt schema ${schema}). Run: npx promptdock@latest ${argsLine}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
+}
+/** Collect the receipts a lifecycle command operates on. */
+function collect(ctx, flags, refArg) {
+    if (typeof flags.dir === "string") {
+        const dir = isAbsolute(flags.dir) ? flags.dir : resolvePath(ctx.cwd, flags.dir);
+        const read = readReceipt(dir);
+        if (read.kind === "none") {
+            throw new CliError(`no promptdock receipt in ${dir} — nothing to manage there (the CLI only touches files it installed)`, EXIT.DENIED, { footer: "no_receipt" });
+        }
+        return [{ dir, targetId: "custom", scope: "local", read }];
+    }
+    const scope = scopeOf(flags);
+    const targetId = typeof flags.target === "string" ? flags.target : undefined;
+    let items = scanReceipts({ cwd: ctx.cwd, home: ctx.home, scope, targetId });
+    if (refArg) {
+        const ref = parseSkillRef(refArg);
+        if (!ref) {
+            throw usageError(`"${refArg}" isn't a valid skill ref`, "expected handle/slug");
+        }
+        const wanted = formatRef(ref);
+        items = items.filter((i) => i.read.kind === "ok" && i.read.receipt.ref === wanted);
+        if (items.length === 0) {
+            throw new CliError(`${wanted} is not installed in this scope — try -g (global) or --all, and \`npx promptdock@latest list --all\` to see what's installed`, EXIT.DENIED, { footer: "not_installed" });
+        }
+    }
+    return items;
+}
+/* ── uninstall ──────────────────────────────────────────────────────────────── */
+export async function runUninstall(ctx, positionals, flags) {
+    const refArg = positionals[0];
+    if (!refArg && flags.all !== true && typeof flags.dir !== "string") {
+        throw usageError("pass a skill ref, --all, or --dir <path>", "usage: promptdock uninstall <handle>/<slug>");
+    }
+    const c = colors(ctx.env, ctx.io.isTTY);
+    const items = collect(ctx, flags, refArg);
+    const removed = [];
+    for (const item of items) {
+        if (item.read.kind === "newer_schema") {
+            throw newerSchemaError(item.dir, item.read.schema, ctx.argsLine);
+        }
+        if (item.read.kind !== "ok") {
+            throw new CliError(`${item.dir} has an unreadable receipt — refusing to guess what to delete (remove the directory manually if you're sure)`, EXIT.INTEGRITY, { footer: "receipt_invalid" });
+        }
+        const receipt = item.read.receipt;
+        // DX5 local-edit guard: human work never dies to a default.
+        const modified = modifiedFiles(item.dir, receipt).filter((p) => existsSync(join(item.dir, p)));
+        if (modified.length > 0 && flags.force !== true) {
+            throw new CliError(`local changes in ${modified.length} file(s) under ${item.dir} (${modified.slice(0, 3).join(", ")}${modified.length > 3 ? ", …" : ""}) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" });
+        }
+        if (flags.yes !== true) {
+            if (!ctx.io.isTTY)
+                throw usageError("confirmation needed in a non-interactive session", "re-run with -y");
+            const go = await confirm(ctx.io, `Uninstall ${receipt.ref} from ${item.dir}?`, false);
+            if (!go) {
+                ctx.io.out("Skipped.");
+                continue;
+            }
+        }
+        removeReceiptOwned(item.dir, receipt);
+        removed.push({ ref: receipt.ref, dir: item.dir });
+        if (flags.json !== true)
+            ctx.io.out(`${c.green("✓")} Uninstalled ${receipt.ref} (${item.dir})`);
+    }
+    if (flags.json === true)
+        ctx.io.out(JSON.stringify({ uninstalled: removed }));
+    else if (removed.length === 0)
+        ctx.io.out("Nothing uninstalled.");
+}
+/**
+ * Remove ONLY what the receipt lists (+ the receipt), then prune emptied dirs
+ * bottom-up. lstat semantics: a symlink is removed as the LINK — never followed
+ * (a link pointing outside the dir must not delete its target's content).
+ */
+function removeReceiptOwned(dir, receipt) {
+    for (const f of receipt.files) {
+        const abs = join(dir, f.path);
+        try {
+            const st = lstatSync(abs);
+            if (st.isDirectory())
+                continue; // a dir where a file should be — leave it
+            unlinkSync(abs); // removes files AND symlinks (the link itself)
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw mapFsError(err, abs);
+        }
+    }
+    try {
+        rmSync(join(dir, RECEIPT_NAME), { force: true });
+    }
+    catch (err) {
+        throw mapFsError(err, join(dir, RECEIPT_NAME));
+    }
+    // Prune emptied subdirectories (deepest first), then the skill dir itself.
+    const subdirs = new Set();
+    for (const f of receipt.files) {
+        let d = dirname(f.path);
+        while (d !== "." && d !== "/") {
+            subdirs.add(d);
+            d = dirname(d);
+        }
+    }
+    const ordered = [...subdirs].sort((a, b) => b.split("/").length - a.split("/").length);
+    for (const rel of ordered) {
+        try {
+            rmdirSync(join(dir, rel));
+        }
+        catch {
+            /* not empty / already gone — fine */
+        }
+    }
+    try {
+        rmdirSync(dir);
+    }
+    catch {
+        /* contains user files — deliberately left in place */
+    }
+}
+/* ── update ─────────────────────────────────────────────────────────────────── */
+export async function runUpdate(ctx, positionals, flags) {
+    const c = colors(ctx.env, ctx.io.isTTY);
+    const checkOnly = flags.check === true;
+    const json = flags.json === true;
+    const items = collect(ctx, flags, positionals[0]);
+    if (items.length === 0) {
+        ctx.io.out(json ? JSON.stringify({ updated: [], checked: [] }) : "No promptdock skills installed in this scope.");
+        return;
+    }
+    const { api } = await ensureAuth(ctx);
+    const report = [];
+    for (const item of items) {
+        if (item.read.kind === "newer_schema") {
+            throw newerSchemaError(item.dir, item.read.schema, ctx.argsLine);
+        }
+        if (item.read.kind !== "ok")
+            continue;
+        const receipt = item.read.receipt;
+        let resolved;
+        try {
+            resolved = await api.request("GET", `/api/v1/cli/skills/resolve?ref=${encodeURIComponent(receipt.ref)}`);
+            assertInstallable(resolved, receipt.ref);
+        }
+        catch (err) {
+            const reason = err instanceof CliError ? err.message : String(err);
+            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: null, status: "skipped", reason });
+            if (!json)
+                ctx.io.out(`${c.yellow("!")} ${receipt.ref}: ${reason}`);
+            continue;
+        }
+        if (resolved.version_id === receipt.version_id) {
+            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: receipt.version, status: "up_to_date" });
+            if (!json)
+                ctx.io.out(`${c.dim("·")} ${receipt.ref} is up to date (v${receipt.version})`);
+            continue;
+        }
+        const toVersion = Number(resolved.version) || 0;
+        if (checkOnly) {
+            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "available" });
+            if (!json)
+                ctx.io.out(`${c.cyan("↑")} ${receipt.ref}: v${receipt.version} → v${toVersion} available`);
+            continue;
+        }
+        // DX5 local-edit guard BEFORE any overwrite.
+        const modified = modifiedFiles(item.dir, receipt);
+        if (modified.length > 0 && flags.force !== true) {
+            const reason = `local changes in ${modified.length} file(s) — --force to overwrite`;
+            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason });
+            if (!json)
+                ctx.io.out(`${c.yellow("!")} ${receipt.ref}: ${reason}`);
+            continue;
+        }
+        if (flags.yes !== true) {
+            if (!ctx.io.isTTY)
+                throw usageError("confirmation needed in a non-interactive session", "re-run with -y (or use --check)");
+            const go = await confirm(ctx.io, `Update ${receipt.ref} v${receipt.version} → v${toVersion}?`, true);
+            if (!go) {
+                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason: "declined" });
+                continue;
+            }
+        }
+        if (typeof resolved.skill_id !== "string" || typeof resolved.version_id !== "string")
+            continue;
+        const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolved.skill_id}/install`, { version_id: resolved.version_id });
+        const resp = checkInstallResponse(respRaw);
+        await performInstall(ctx, api, {
+            resp,
+            targetDir: item.dir,
+            targetId: item.targetId,
+            refString: receipt.ref,
+            prior: receipt,
+        });
+        report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: resp.skill.version, status: "updated" });
+        if (!json)
+            ctx.io.out(`${c.green("✓")} ${receipt.ref}: v${receipt.version} → v${resp.skill.version}`);
+    }
+    if (json)
+        ctx.io.out(JSON.stringify({ results: report }));
+}
+/* ── list ───────────────────────────────────────────────────────────────────── */
+export async function runList(ctx, flags) {
+    const scope = scopeOf(flags);
+    const items = scanReceipts({ cwd: ctx.cwd, home: ctx.home, scope });
+    if (flags.json === true) {
+        ctx.io.out(JSON.stringify(items.map((i) => ({
+            dir: i.dir,
+            target: i.targetId,
+            scope: i.scope,
+            ...(i.read.kind === "ok"
+                ? {
+                    ref: i.read.receipt.ref,
+                    version: i.read.receipt.version,
+                    version_id: i.read.receipt.version_id,
+                    installed_at: i.read.receipt.installed_at,
+                    schema: i.read.receipt.schema,
+                }
+                : { receipt: i.read.kind }),
+        }))));
+        return;
+    }
+    if (items.length === 0) {
+        ctx.io.out(scope === "local"
+            ? "No promptdock skills installed in this project. Try -g (global) or --all."
+            : "No promptdock skills installed in this scope.");
+        return;
+    }
+    for (const i of items) {
+        if (i.read.kind === "ok") {
+            const r = i.read.receipt;
+            const when = typeof r.installed_at === "string" ? r.installed_at.slice(0, 10) : "?";
+            ctx.io.out(`${r.ref}  v${r.version}  ${i.targetId} (${i.scope})  ${when}  ${i.dir}`);
+        }
+        else {
+            ctx.io.out(`?  ${i.dir}  (${i.read.kind === "newer_schema" ? "newer receipt schema — run npx promptdock@latest" : "unreadable receipt"})`);
+        }
+    }
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,4 @@
+import type { CliContext } from "../context.js";
+export declare function runLogin(ctx: CliContext, flags: Record<string, string | boolean>): Promise<void>;
+export declare function runLogout(ctx: CliContext): Promise<void>;
+export declare function runWhoami(ctx: CliContext, flags: Record<string, string | boolean>): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,58 @@
+// `promptdock login [--token pdk_…]` — device flow, or store a Settings-minted
+// CI token (DX6). Explicit `login` works in non-TTY too (the device flow needs
+// no keyboard — CI users should prefer PROMPTDOCK_TOKEN, but an explicit
+// invocation shouldn't refuse); the browser only auto-opens on a TTY.
+import { Api } from "../api.js";
+import { deviceFlowLogin } from "../auth.js";
+import { loadConfig, resolveApiBase, saveConfig } from "../config.js";
+import { usageError } from "../errors.js";
+import { colors } from "../ui.js";
+export async function runLogin(ctx, flags) {
+    const c = colors(ctx.env, ctx.io.isTTY);
+    const config = loadConfig(ctx.home);
+    const baseUrl = resolveApiBase(ctx.env, config);
+    let token;
+    if (typeof flags.token === "string") {
+        if (!flags.token.startsWith("pdk_")) {
+            throw usageError("--token expects a pdk_… token (Settings → Account → CLI sessions → Generate token)");
+        }
+        token = flags.token;
+    }
+    else {
+        token = await deviceFlowLogin(ctx, baseUrl, { long: false });
+    }
+    // Verify BEFORE storing (a typo'd --token should fail here, not at first use).
+    const api = new Api(ctx, baseUrl, token);
+    const who = await api.request("GET", "/api/v1/cli/whoami");
+    saveConfig(ctx.home, { ...config, token, api_base: baseUrl }, ctx.platform);
+    const name = who.handle ? `@${who.handle}` : "your account";
+    ctx.io.out(`${c.green("✓")} Logged in as ${name}${who.role ? ` (${who.role})` : ""}.`);
+    if (ctx.env.PROMPTDOCK_TOKEN) {
+        ctx.io.out(c.dim("note: PROMPTDOCK_TOKEN is set and overrides the stored login."));
+    }
+}
+export async function runLogout(ctx) {
+    const config = loadConfig(ctx.home);
+    const had = typeof config.token === "string";
+    if (had) {
+        delete config.token;
+        saveConfig(ctx.home, config, ctx.platform);
+    }
+    ctx.io.out(had ? "Logged out (local token removed)." : "Not logged in — nothing to remove.");
+    ctx.io.out("To invalidate the session server-side too: promptdock.ai → Settings → Account → CLI sessions → Revoke.");
+    if (ctx.env.PROMPTDOCK_TOKEN) {
+        ctx.io.out("note: PROMPTDOCK_TOKEN is set in this environment and still authenticates requests.");
+    }
+}
+export async function runWhoami(ctx, flags) {
+    const { ensureAuth } = await import("../auth.js");
+    const { api } = await ensureAuth(ctx);
+    const who = await api.request("GET", "/api/v1/cli/whoami");
+    if (flags.json === true) {
+        ctx.io.out(JSON.stringify(who));
+        return;
+    }
+    const name = who.handle ? `@${who.handle}` : "(no handle)";
+    const expiry = who.expires_at ? new Date(who.expires_at).toISOString().slice(0, 10) : "unknown";
+    ctx.io.out(`Signed in as ${name} · role: ${who.role} · token expires: ${expiry}`);
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_API_BASE = "https://promptdock.ai";
+export type CliConfig = {
+    token?: string;
+    api_base?: string;
+    [key: string]: unknown;
+};
+export declare function configDir(home: string): string;
+export declare function configPath(home: string): string;
+export declare function loadConfig(home: string): CliConfig;
+/**
+ * Write the config with owner-only perms. POSIX: mode 0600 enforced + VERIFIED
+ * (fail-closed — DX6). Windows: chmod is a no-op by design; the user profile
+ * dir's ACL is the boundary there (documented in the README).
+ */
+export declare function saveConfig(home: string, config: CliConfig, platform: NodeJS.Platform): void;
+/** Env override first (CI contract), then the stored token. Never logged. */
+export declare function resolveToken(env: Record<string, string | undefined>, config: CliConfig): string | null;
+export declare function resolveApiBase(env: Record<string, string | undefined>, config: CliConfig): string;

package/dist/config.js

@@ -0,0 +1,64 @@
+// ~/.promptdock/config.json — {token, api_base}. chmod 600, FAIL-CLOSED (DX6):
+// if the file can't be locked down to owner-only on a POSIX system, it is
+// removed and the save throws — a world-readable bearer token is worse than a
+// re-login. Env overrides: PROMPTDOCK_TOKEN (CI), PROMPTDOCK_API_BASE.
+import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError, EXIT } from "./errors.js";
+export const DEFAULT_API_BASE = "https://promptdock.ai";
+export function configDir(home) {
+    return join(home, ".promptdock");
+}
+export function configPath(home) {
+    return join(configDir(home), "config.json");
+}
+export function loadConfig(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(home), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write the config with owner-only perms. POSIX: mode 0600 enforced + VERIFIED
+ * (fail-closed — DX6). Windows: chmod is a no-op by design; the user profile
+ * dir's ACL is the boundary there (documented in the README).
+ */
+export function saveConfig(home, config, platform) {
+    const dir = configDir(home);
+    const file = configPath(home);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+        if (platform !== "win32") {
+            chmodSync(file, 0o600);
+            const mode = statSync(file).mode & 0o777;
+            if ((mode & 0o077) !== 0) {
+                throw new Error(`config file mode is ${mode.toString(8)}, expected 600`);
+            }
+        }
+    }
+    catch (err) {
+        // Fail closed: never leave a token in a file we couldn't lock down.
+        try {
+            rmSync(file, { force: true });
+        }
+        catch {
+            /* best effort */
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CliError(`couldn't secure ${file} (${detail}) — the token was NOT saved. Fix the directory permissions and retry, or use the PROMPTDOCK_TOKEN env variable.`, EXIT.IO, { footer: "config" });
+    }
+}
+/** Env override first (CI contract), then the stored token. Never logged. */
+export function resolveToken(env, config) {
+    return env.PROMPTDOCK_TOKEN || (typeof config.token === "string" ? config.token : null) || null;
+}
+export function resolveApiBase(env, config) {
+    const base = env.PROMPTDOCK_API_BASE ||
+        (typeof config.api_base === "string" ? config.api_base : null) ||
+        DEFAULT_API_BASE;
+    return base.replace(/\/+$/, "");
+}

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+/** I/O seam — commands never touch process.* directly (unit tests inject fakes). */
+export type CliIo = {
+    /** stdout line */
+    out: (s: string) => void;
+    /** stderr line */
+    err: (s: string) => void;
+    /** raw stdout write (countdown repaint; no newline) */
+    write: (s: string) => void;
+    /** true only when stdin AND stdout are interactive (D-UX11 non-TTY contract) */
+    isTTY: boolean;
+    /** readline question (TTY only — callers must gate on isTTY) */
+    question: (prompt: string) => Promise<string>;
+};
+export type CliContext = {
+    io: CliIo;
+    env: Record<string, string | undefined>;
+    cwd: string;
+    home: string;
+    platform: NodeJS.Platform;
+    fetch: typeof fetch;
+    /** the CLI's own version (rides X-Promptdock-Cli-Version + the UA) */
+    version: string;
+    /** the invocation's args, space-joined (X-Promptdock-Cli-Args — 426 remedy echo) */
+    argsLine: string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    /** best-effort browser open; NEVER throws (failure → the caller printed the URL) */
+    openUrl: (url: string) => void;
+};
+/** Read the package's own version (dist/ and src/ both sit one level under the root). */
+export declare function readOwnVersion(): string;
+/** Best-effort platform browser open (darwin `open`, win32 `start`, else xdg-open). */
+export declare function openUrlBestEffort(url: string, platform: NodeJS.Platform): void;
+export declare function realContext(argv: string[]): CliContext;