hatchkit 0.1.1 → 0.1.3

package/dist/doctor.js

@@ -0,0 +1,368 @@
+/*
+ * `hatchkit doctor` — health check for every configured provider.
+ *
+ * Runs the cheapest idempotent verification call that proves the stored
+ * credential still works (GET-only, no writes). Reports a summary.
+ */
+import chalk from "chalk";
+import { getCoolifyConfig, getDnsConfig, getGlitchtipConfig, getHetznerConfig, getOpenpanelConfig, getResendConfig, getS3Config, getStore, } from "./config.js";
+import { verifyCoolify } from "./utils/coolify-api.js";
+import { execOk } from "./utils/exec.js";
+import { SECRET_KEYS, getSecret } from "./utils/secrets.js";
+async function check(name, fn, hintFn) {
+    try {
+        const detail = await fn();
+        return { name, status: "ok", detail: detail || undefined };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { name, status: "fail", detail, hint: hintFn?.(detail) };
+    }
+}
+/** Pull the HTTP status code out of a "HTTP 401 ..." style error message. */
+function httpCode(detail) {
+    const m = detail.match(/HTTP (\d{3})/);
+    return m ? Number(m[1]) : undefined;
+}
+async function checkGitHub() {
+    if (!(await execOk("gh", ["--version"]))) {
+        return {
+            name: "GitHub (gh CLI)",
+            status: "fail",
+            detail: "gh CLI not installed",
+            hint: [
+                "Install: `brew install gh` (macOS) or see https://cli.github.com",
+                "Then authenticate: `gh auth login`",
+            ],
+        };
+    }
+    if (!(await execOk("gh", ["auth", "status"]))) {
+        return {
+            name: "GitHub (gh CLI)",
+            status: "fail",
+            detail: "not authenticated",
+            hint: ["Run `gh auth login` and pick GitHub.com → HTTPS → browser."],
+        };
+    }
+    return { name: "GitHub (gh CLI)", status: "ok" };
+}
+async function checkCoolify() {
+    const cfg = await getCoolifyConfig();
+    if (!cfg)
+        return { name: "Coolify", status: "skip" };
+    return check("Coolify", async () => {
+        const v = await verifyCoolify(cfg.url, cfg.token);
+        return `v${v}`;
+    }, (detail) => {
+        const code = httpCode(detail);
+        if (code === 401 || code === 403) {
+            return [
+                "API token invalid or expired.",
+                `Create a new one: ${cfg.url.replace(/\/$/, "")}/security/api-tokens`,
+                "Then re-run: `hatchkit config add coolify`",
+            ];
+        }
+        if (/ENOTFOUND|ECONNREFUSED|fetch failed/i.test(detail)) {
+            return [
+                `Can't reach Coolify at ${cfg.url}.`,
+                "Check the URL is reachable from this machine, or re-run `hatchkit config add coolify`.",
+            ];
+        }
+        return undefined;
+    });
+}
+async function checkHetzner() {
+    const cfg = await getHetznerConfig();
+    if (!cfg)
+        return { name: "Hetzner Cloud", status: "skip" };
+    return check("Hetzner Cloud", async () => {
+        const res = await fetch("https://api.hetzner.cloud/v1/servers?per_page=1", {
+            headers: { Authorization: `Bearer ${cfg.token}` },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const body = (await res.json());
+        return `${body.meta?.pagination?.total_entries ?? "?"} server(s)`;
+    }, (detail) => {
+        const code = httpCode(detail);
+        if (code === 401) {
+            return [
+                "Hetzner API token is invalid or was revoked.",
+                "Create a new one: https://console.hetzner.cloud/ → project → Security → API tokens (Read & Write)",
+                "Then re-run: `hatchkit config add hetzner`",
+            ];
+        }
+        if (code === 403) {
+            return [
+                "Token lacks permissions — needs Read & Write on the project.",
+                "Re-create it and re-run `hatchkit config add hetzner`.",
+            ];
+        }
+        return undefined;
+    });
+}
+async function checkDns() {
+    const cfg = await getDnsConfig();
+    if (!cfg || cfg.provider === "manual")
+        return { name: "DNS", status: "skip" };
+    if (cfg.provider === "cloudflare") {
+        return check("DNS (Cloudflare)", async () => {
+            const res = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+                headers: { Authorization: `Bearer ${cfg.apiToken}` },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = (await res.json());
+            return body.result?.status ?? "active";
+        }, (detail) => {
+            const code = httpCode(detail);
+            if (code === 401) {
+                return [
+                    "Cloudflare API token is invalid, expired, or revoked.",
+                    "Create a new one: https://dash.cloudflare.com/profile/api-tokens",
+                    "Required permissions: Zone:DNS:Edit + Zone:Zone:Read (scope to the zones you'll use).",
+                    "Then re-run: `hatchkit config add dns`",
+                ];
+            }
+            if (code === 403) {
+                return [
+                    "Token authenticates but lacks Zone:DNS:Edit + Zone:Zone:Read on the target zones.",
+                    "Edit the token at https://dash.cloudflare.com/profile/api-tokens or create a new one, then `hatchkit config add dns`.",
+                ];
+            }
+            return undefined;
+        });
+    }
+    // INWX uses XML-RPC login — skip active-verify (cheap check would require a login call).
+    return {
+        name: "DNS (INWX)",
+        status: "ok",
+        detail: "credentials stored (not test-authenticated)",
+    };
+}
+async function checkS3(provider) {
+    const name = `S3 (${provider})`;
+    const cfg = await getS3Config(provider);
+    if (!cfg)
+        return { name, status: "skip" };
+    // Stored creds only — a real verify would require an AWS SDK call.
+    return { name, status: "ok", detail: "credentials stored (endpoint set)" };
+}
+async function checkGpu(platform) {
+    const store = getStore();
+    const meta = store.get(`providers.gpu.${platform}`);
+    const name = `GPU (${platform})`;
+    if (meta?.status !== "configured")
+        return { name, status: "skip" };
+    if (platform === "modal") {
+        return check(name, async () => {
+            if (!(await execOk("modal", ["token", "current"])))
+                throw new Error("`modal token current` failed");
+            return "authenticated";
+        });
+    }
+    const key = await getSecret(SECRET_KEYS.gpuApiKey(platform));
+    if (!key) {
+        return {
+            name,
+            status: "fail",
+            detail: "API key missing from keychain",
+            hint: [`Re-run: \`hatchkit config add gpu\` and pick ${platform}.`],
+        };
+    }
+    const gpuHint = (label, createUrl) => (detail) => {
+        const code = httpCode(detail);
+        if (code === 401 || code === 403) {
+            return [
+                `${label} API key is invalid or expired.`,
+                `Create a new one: ${createUrl}`,
+                "Then re-run: `hatchkit config add gpu`",
+            ];
+        }
+        return undefined;
+    };
+    if (platform === "hf") {
+        return check(name, async () => {
+            const res = await fetch("https://huggingface.co/api/whoami-v2", {
+                headers: { Authorization: `Bearer ${key}` },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = (await res.json());
+            return body.name ?? "authenticated";
+        }, gpuHint("Hugging Face", "https://huggingface.co/settings/tokens"));
+    }
+    if (platform === "replicate") {
+        return check(name, async () => {
+            const res = await fetch("https://api.replicate.com/v1/account", {
+                headers: { Authorization: `Token ${key}` },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            return "authenticated";
+        }, gpuHint("Replicate", "https://replicate.com/account/api-tokens"));
+    }
+    if (platform === "runpod") {
+        return check(name, async () => {
+            const res = await fetch("https://rest.runpod.io/v1/user", {
+                headers: { Authorization: `Bearer ${key}` },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            return "authenticated";
+        }, gpuHint("RunPod", "https://www.runpod.io/console/user/settings"));
+    }
+    return { name, status: "ok", detail: "credentials stored" };
+}
+async function checkGlitchtip() {
+    const cfg = await getGlitchtipConfig();
+    if (!cfg)
+        return { name: "GlitchTip", status: "skip" };
+    return check("GlitchTip", async () => {
+        const res = await fetch(`${cfg.url}/api/0/organizations/${cfg.organizationSlug}/`, {
+            headers: { Authorization: `Bearer ${cfg.token}` },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return `org: ${cfg.organizationSlug}`;
+    }, (detail) => {
+        const code = httpCode(detail);
+        const base = cfg.url.replace(/\/$/, "");
+        if (code === 401) {
+            return [
+                "Auth token is invalid or expired.",
+                `Create a new one: ${base}/profile/auth-tokens`,
+                "Then re-run: `hatchkit config add glitchtip`",
+            ];
+        }
+        if (code === 404) {
+            return [
+                `Organization "${cfg.organizationSlug}" not found — slug may be wrong.`,
+                `Check at ${base}/ and re-run: \`hatchkit config add glitchtip\``,
+            ];
+        }
+        return undefined;
+    });
+}
+async function checkOpenpanel() {
+    const cfg = await getOpenpanelConfig();
+    if (!cfg)
+        return { name: "OpenPanel", status: "skip" };
+    const manageBase = `${(cfg.apiUrl ?? cfg.url).replace(/\/$/, "")}/manage`;
+    return check("OpenPanel", async () => {
+        const res = await fetch(`${manageBase}/projects`, {
+            headers: {
+                "openpanel-client-id": cfg.rootClientId,
+                "openpanel-client-secret": cfg.rootClientSecret,
+            },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return `root client OK`;
+    }, (detail) => {
+        const code = httpCode(detail);
+        if (code === 401 || code === 403) {
+            return [
+                "Root client credentials rejected — may have been rotated or lack `write` access.",
+                "Re-run: `hatchkit config add openpanel` and paste the root client id/secret.",
+            ];
+        }
+        if (/Only HTML requests|<html/i.test(detail) || code === 404) {
+            return [
+                `Management API base URL looks wrong — response isn't JSON.`,
+                `Current: ${manageBase}`,
+                "Self-hosted OpenPanel puts the API on a separate subdomain (typically `api.<dashboard>`).",
+                "Re-run: `hatchkit config add openpanel` and set the API URL explicitly.",
+            ];
+        }
+        return undefined;
+    });
+}
+async function checkResend() {
+    const cfg = await getResendConfig();
+    if (!cfg)
+        return { name: "Resend", status: "skip" };
+    return check("Resend", async () => {
+        const res = await fetch("https://api.resend.com/domains", {
+            headers: { Authorization: `Bearer ${cfg.apiKey}` },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return "API key valid";
+    }, (detail) => {
+        const code = httpCode(detail);
+        if (code === 401) {
+            return [
+                "Resend API key is invalid or was deleted.",
+                "Create a new one (full access): https://resend.com/api-keys",
+                "Then re-run: `hatchkit config add resend`",
+            ];
+        }
+        if (code === 403) {
+            return [
+                "API key lacks permissions — needs `Full access` to list/create domains and keys.",
+                "Re-create at https://resend.com/api-keys and re-run `hatchkit config add resend`.",
+            ];
+        }
+        return undefined;
+    });
+}
+export async function collectDoctorResults() {
+    const results = [];
+    results.push(await checkGitHub());
+    results.push(await checkCoolify());
+    results.push(await checkHetzner());
+    results.push(await checkDns());
+    for (const p of ["hetzner", "aws", "r2"])
+        results.push(await checkS3(p));
+    for (const p of ["modal", "runpod", "hf", "replicate"])
+        results.push(await checkGpu(p));
+    results.push(await checkGlitchtip());
+    results.push(await checkOpenpanel());
+    results.push(await checkResend());
+    return results;
+}
+export async function runDoctor(opts = {}) {
+    const results = await collectDoctorResults();
+    const okCount = results.filter((r) => r.status === "ok").length;
+    const failCount = results.filter((r) => r.status === "fail").length;
+    const skipCount = results.filter((r) => r.status === "skip").length;
+    if (opts.json) {
+        const payload = {
+            summary: { ok: okCount, failing: failCount, not_configured: skipCount },
+            checks: results.map((r) => ({
+                name: r.name,
+                status: r.status,
+                detail: r.detail,
+                hint: r.hint,
+            })),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        if (failCount > 0)
+            process.exit(1);
+        return;
+    }
+    console.log(chalk.bold("  hatchkit doctor — checking configured providers\n"));
+    for (const r of results) {
+        const icon = r.status === "ok" ? chalk.green("✓") : r.status === "fail" ? chalk.red("✗") : chalk.dim("·");
+        const name = r.status === "fail" ? chalk.red(r.name) : r.name;
+        const detail = r.detail ? chalk.dim(` — ${r.detail}`) : "";
+        console.log(`  ${icon} ${name}${detail}`);
+    }
+    console.log(`\n  ${chalk.green(`${okCount} ok`)}  ${failCount ? chalk.red(`${failCount} failing`) : chalk.dim("0 failing")}  ${chalk.dim(`${skipCount} not configured`)}\n`);
+    const failed = results.filter((r) => r.status === "fail");
+    if (failed.length > 0) {
+        console.log(chalk.bold("  How to fix"));
+        for (const r of failed) {
+            console.log(`\n  ${chalk.red("✗")} ${chalk.bold(r.name)}`);
+            const lines = r.hint ?? [
+                "No specific hint — try re-running the relevant `hatchkit config add <provider>` to re-enter credentials.",
+            ];
+            for (const line of lines)
+                console.log(`    ${chalk.dim("→")} ${line}`);
+        }
+        console.log();
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/explain.d.ts

@@ -0,0 +1,4 @@
+export declare function renderExplain(opts: {
+    json: boolean;
+}): string;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAqJA,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAoD7D"}

package/dist/explain.js

@@ -0,0 +1,173 @@
+/*
+ * `hatchkit explain` — one-page mental model. Written so a human with
+ * zero context (or an agent encountering hatchkit for the first time)
+ * can read it top-to-bottom and understand what the CLI does, what it
+ * owns, and the canonical workflow.
+ *
+ * Update the `CONCEPTS` / `COMMANDS` / `WORKFLOW` blocks in one place
+ * and both the human text and the JSON payload stay in sync.
+ */
+import chalk from "chalk";
+const MODEL = {
+    tagline: "Scaffold, deploy, and provision full-stack projects on your own infra.",
+    what_it_does: [
+        "Scaffolds opinionated full-stack projects (web + optional desktop/mobile + optional ML) from a starter template.",
+        "Wires them up to your own infra: Hetzner (server), DNS (Cloudflare/INWX), Coolify (deploys), GitHub (repo).",
+        "Provisions per-project clients in third-party services (GlitchTip errors, OpenPanel analytics, Resend email).",
+        "Manages per-project dotenvx private keys in your OS keychain.",
+    ],
+    concepts: [
+        {
+            name: "Provider",
+            description: "An external service (GitHub, Hetzner, Coolify, DNS, S3, GPU, GlitchTip, OpenPanel, Resend). Each is configured once; credentials go to the OS keychain, metadata to ~/<conf-dir>/config.json.",
+        },
+        {
+            name: "Project",
+            description: "A scaffolded repo with a .hatchkit.json manifest. Has a name (kebab-case), a domain, a feature set (desktop/mobile/s3/ml), and per-project ports.",
+        },
+        {
+            name: "Client",
+            description: "A per-project credential in a provider — e.g. a Resend API key scoped to one project, a GlitchTip DSN, an OpenPanel client id/secret. `hatchkit add` creates `-dev` and `-prod` pairs.",
+        },
+        {
+            name: "Manifest",
+            description: ".hatchkit.json at the project root. Records which features were scaffolded so `hatchkit update` knows what's already there.",
+        },
+        {
+            name: "dotenvx key",
+            description: "Per-project private key that decrypts .env.production at runtime. Generated at scaffold time; lives in the OS keychain under service `hatchkit`; pushed to Coolify via `hatchkit keys push`.",
+        },
+    ],
+    commands: [
+        {
+            name: "hatchkit setup",
+            summary: "One-time onboarding — wires up GitHub + Coolify + Hetzner + DNS + optional extras.",
+            when: "First time you ever use hatchkit on a machine.",
+        },
+        {
+            name: "hatchkit status",
+            summary: "Show which providers are configured and what's the next best step.",
+            when: "To get oriented, or after setup to confirm state.",
+        },
+        {
+            name: "hatchkit doctor",
+            summary: "Live-verify every configured provider with a read-only API call; contextual fix hints on failures.",
+            when: "When something's broken, before a deploy, or as a CI sanity check.",
+        },
+        {
+            name: "hatchkit create",
+            summary: "Scaffold (and optionally deploy) a new project. Interactive.",
+            when: "Starting a new project.",
+        },
+        {
+            name: "hatchkit update",
+            summary: "Add features (desktop, mobile) to an already-scaffolded project.",
+            when: "`cd <project-dir>` first; expands an existing scaffold.",
+        },
+        {
+            name: "hatchkit add <project>",
+            summary: "Provision GlitchTip / OpenPanel / Resend clients for an existing project (creates -dev + -prod pair each).",
+            when: "After the scaffold is live and you're ready to wire up observability / email.",
+        },
+        {
+            name: "hatchkit keys show <project>",
+            summary: "Print the project's DOTENV_PRIVATE_KEY_PRODUCTION from the keychain.",
+            when: "To hand the key to CI / another machine / manually paste into Coolify.",
+        },
+        {
+            name: "hatchkit keys push <project>",
+            summary: "Upsert the private key onto the project's Coolify app via API.",
+            when: "After scaffold + initial Coolify deploy, so the app can decrypt env at runtime.",
+        },
+        {
+            name: "hatchkit config add <provider>",
+            summary: "Configure one provider (coolify / hetzner / dns / s3 / gpu / glitchtip / openpanel / resend).",
+            when: "Rotating a token, or adding an optional provider you skipped during setup.",
+        },
+        {
+            name: "hatchkit explain",
+            summary: "This screen. `--json` for a structured payload.",
+            when: "Anytime a zero-context reader (human or agent) needs the mental model.",
+        },
+    ],
+    workflow: [
+        "1. `hatchkit setup` — configure credentials once (per machine).",
+        "2. `hatchkit status` — confirm everything's green.",
+        "3. `hatchkit create` — scaffold a new project; pick features, deploy target, ML services.",
+        "4. `hatchkit add <project>` — provision per-project clients (GlitchTip, OpenPanel, Resend).",
+        "5. `hatchkit keys push <project>` — ship the dotenvx key to Coolify so prod can decrypt.",
+        "6. `hatchkit doctor` — sanity-check before/after anything risky.",
+        "7. `hatchkit update` (from project dir) — extend an existing project with new features.",
+    ],
+    provider_glossary: [
+        { name: "GitHub", role: "Hosts the project repo. Uses the `gh` CLI for auth." },
+        { name: "Coolify", role: "Self-hosted PaaS. Deploys apps on your Hetzner box." },
+        { name: "Hetzner Cloud", role: "VMs (and optional S3 object storage) for new deploy targets." },
+        { name: "DNS (Cloudflare / INWX)", role: "Automates domain records during Terraform." },
+        { name: "S3 (Hetzner / AWS / R2)", role: "Optional object storage — picked per-project." },
+        {
+            name: "GPU (Modal / RunPod / HF / Replicate)",
+            role: "Optional inference backends for ML services.",
+        },
+        { name: "GlitchTip", role: "Self-hostable Sentry-compatible error tracking." },
+        { name: "OpenPanel", role: "Privacy-friendly product analytics." },
+        { name: "Resend", role: "Transactional email; keys can be scoped to a sending domain." },
+    ],
+    state_locations: [
+        {
+            what: "Provider metadata (no secrets)",
+            where: "~/<conf-dir>/config.json via the `conf` package",
+        },
+        {
+            what: "Secrets (tokens, keys)",
+            where: "OS keychain under service `hatchkit` (macOS Keychain / libsecret)",
+        },
+        { what: "Provisioned env blocks", where: "~/<conf-dir>/provisioned/<project>.{dev,prod}.env" },
+        { what: "Project manifest", where: "<project-dir>/.hatchkit.json" },
+    ],
+};
+export function renderExplain(opts) {
+    if (opts.json) {
+        return JSON.stringify(MODEL, null, 2);
+    }
+    const out = [];
+    const b = (s) => chalk.bold(s);
+    const dim = (s) => chalk.dim(s);
+    out.push(b("  hatchkit — the mental model"));
+    out.push(`  ${MODEL.tagline}`);
+    out.push("");
+    out.push(b("  What it does"));
+    for (const line of MODEL.what_it_does)
+        out.push(`    · ${line}`);
+    out.push("");
+    out.push(b("  Concepts"));
+    for (const c of MODEL.concepts) {
+        out.push(`    ${chalk.cyan(c.name)}`);
+        out.push(`      ${c.description}`);
+    }
+    out.push("");
+    out.push(b("  Commands"));
+    for (const c of MODEL.commands) {
+        out.push(`    ${chalk.cyan(c.name.padEnd(30))} ${c.summary}`);
+        out.push(`      ${dim(`when: ${c.when}`)}`);
+    }
+    out.push("");
+    out.push(b("  Canonical workflow"));
+    for (const line of MODEL.workflow)
+        out.push(`    ${line}`);
+    out.push("");
+    out.push(b("  Providers at a glance"));
+    for (const p of MODEL.provider_glossary) {
+        out.push(`    ${chalk.cyan(p.name.padEnd(32))} ${p.role}`);
+    }
+    out.push("");
+    out.push(b("  Where state lives"));
+    for (const s of MODEL.state_locations) {
+        out.push(`    ${chalk.cyan(s.what.padEnd(32))} ${s.where}`);
+    }
+    out.push("");
+    out.push(dim("  Tip: `hatchkit status --json` and `hatchkit doctor --json` give agents a machine-readable view."));
+    out.push("");
+    return out.join("\n");
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"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"}