@percher/core 0.2.5 → 0.3.0

package/dist/recovery.js

@@ -0,0 +1,299 @@
+// ── Builders ─────────────────────────────────────────────────────────
+//
+// All recovery construction goes through these. Each builder enforces
+// the required fields for its branch, so a typo or missing field is
+// caught at compile time rather than producing an inline literal that
+// silently violates the contract (e.g. ask_user without prompt).
+/** Success / no-op recovery. `url` is the current live URL when known. */
+export function recoveryNone(opts = {}) {
+    return {
+        retryable: false,
+        nextAction: "none",
+        reasonCode: opts.reasonCode ?? "none",
+        ...(opts.url !== undefined ? { url: opts.url } : {}),
+    };
+}
+/** Authentication required — agent should call `percher_login`. */
+export function recoveryLogin(opts = {}) {
+    return {
+        retryable: false,
+        nextAction: "open_login",
+        suggestedTool: "percher_login",
+        args: {},
+        reasonCode: opts.reasonCode ?? "auth_required",
+    };
+}
+/** Wait on an in-flight deploy — agent should call `percher_wait_for_deploy`. */
+export function recoveryWait(opts) {
+    return {
+        retryable: false,
+        nextAction: "wait_deploy",
+        suggestedTool: "percher_wait_for_deploy",
+        args: {
+            app: opts.app,
+            deployId: opts.deployId,
+            timeoutSeconds: opts.timeoutSeconds ?? 30,
+        },
+        reasonCode: opts.reasonCode,
+    };
+}
+/** Route to `percher_doctor` for an ambiguous failure that needs diagnosis. */
+export function recoveryDoctor(opts) {
+    const args = {};
+    if (opts.app !== undefined)
+        args.app = opts.app;
+    if (opts.deployId !== undefined)
+        args.deployId = opts.deployId;
+    if (opts.mode !== undefined)
+        args.mode = opts.mode;
+    return {
+        retryable: false,
+        nextAction: "run_doctor",
+        suggestedTool: "percher_doctor",
+        args,
+        reasonCode: opts.reasonCode,
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+/** Build/runtime needs env keys — agent should call `percher_env_set`. */
+export function recoveryEnv(opts) {
+    const args = {};
+    if (opts.app !== undefined)
+        args.app = opts.app;
+    if (opts.keys.length > 0)
+        args.keys = opts.keys;
+    return {
+        retryable: false,
+        nextAction: "set_env_vars",
+        suggestedTool: "percher_env_set",
+        args,
+        reasonCode: opts.reasonCode ?? "missing_env",
+    };
+}
+/**
+ * `percher.toml` is invalid or missing — agent should fix the file
+ * directly. `problems` carries the structured issue list (file,
+ * line/column, message) so the agent can apply edits without parsing
+ * a free-text error.
+ */
+export function recoveryFixConfig(opts) {
+    return {
+        retryable: false,
+        nextAction: "fix_config",
+        problems: opts.problems,
+        reasonCode: opts.reasonCode ?? "config_invalid",
+    };
+}
+/**
+ * Build failed and the API extracted at least one structured problem
+ * with file/line data — agent should patch the offending file(s).
+ */
+export function recoveryFixProblems(opts) {
+    return {
+        retryable: false,
+        nextAction: "fix_problems",
+        problems: opts.problems,
+        reasonCode: opts.reasonCode ?? "build_failed",
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+/** Transient infra failure — agent can re-issue the same call. */
+export function recoveryRetry(opts) {
+    return {
+        retryable: true,
+        nextAction: "retry",
+        suggestedTool: opts.suggestedTool,
+        args: opts.args,
+        reasonCode: opts.reasonCode,
+    };
+}
+/**
+ * Human-input required. `prompt` MUST be a concrete question — agents
+ * surface it verbatim, so empty/placeholder strings violate the
+ * contract.
+ */
+export function recoveryAsk(opts) {
+    if (!opts.prompt || opts.prompt.trim().length === 0) {
+        throw new Error("recoveryAsk requires a non-empty prompt");
+    }
+    return {
+        retryable: opts.retryable ?? false,
+        nextAction: "ask_user",
+        prompt: opts.prompt,
+        ...(opts.options !== undefined ? { options: opts.options } : {}),
+        reasonCode: opts.reasonCode,
+    };
+}
+/**
+ * Legacy `inspect_build_log` recovery — kept for the build-failure
+ * paths that haven't migrated to `run_doctor` yet. FUTURE12 Phase 4
+ * will replace these emit sites with `recoveryDoctor`.
+ */
+export function recoveryInspectBuildLog(opts) {
+    const args = opts.deployId
+        ? { id: opts.deployId, app: opts.app }
+        : { latestFailed: true, app: opts.app };
+    return {
+        retryable: false,
+        nextAction: "inspect_build_log",
+        suggestedTool: "percher_deploys_inspect",
+        args,
+        reasonCode: opts.reasonCode ?? "build_failed",
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+// ── Legacy const exports ─────────────────────────────────────────────
+//
+// Kept as concrete values so existing call-sites compile until they
+// migrate to the builders directly. Each is just the corresponding
+// builder evaluated with default reasonCode.
+/** Recovery on the success path. */
+export const RECOVERY_NONE = recoveryNone();
+/** Recovery for the unauthenticated path. */
+export const RECOVERY_NEEDS_LOGIN = recoveryLogin();
+/**
+ * Convert a `BuildProblem` into the lossless `RecoveryProblem` shape.
+ * Drops fields that aren't part of the recovery contract (severity,
+ * code) — those still ride on `error.problems` for the CLI's pretty
+ * printer. `hint` is folded into the message because it carries the
+ * actionable next step (especially for problems without a line, like
+ * malformed package.json) and the recovery contract has no separate
+ * hint slot.
+ *
+ * Exported so doctor (Phase 2c fix_problems path) can reuse the
+ * same hint-preserving mapping rather than re-implementing it.
+ */
+export function buildProblemToRecoveryProblem(p) {
+    // p.file is optional on BuildProblem but the caller filters to
+    // file-bearing problems before reaching here.
+    const file = p.file ?? "";
+    const message = p.hint && p.hint.length > 0 ? `${p.message}\nHint: ${p.hint}` : p.message;
+    return {
+        file,
+        ...(typeof p.line === "number" ? { line: p.line } : {}),
+        ...(typeof p.column === "number" ? { column: p.column } : {}),
+        message,
+    };
+}
+/**
+ * Map an `ErrorClass` to a recovery action. Conservative by default —
+ * unknown classes resolve to `ask_user` so an agent never blindly retries
+ * something we haven't classified.
+ */
+export function recoveryFromErrorClass(errorClass, failure = {}) {
+    switch (errorClass) {
+        case "missing_env":
+            return recoveryEnv({
+                keys: failure.missingEnvVars ?? [],
+                reasonCode: "missing_env",
+            });
+        case "infra_unavailable":
+            return recoveryRetry({
+                suggestedTool: "percher_publish",
+                args: failure.publishInput ?? {},
+                reasonCode: "infra_unavailable",
+            });
+        case "config_invalid":
+            return recoveryFixConfig({
+                problems: [
+                    {
+                        file: "percher.toml",
+                        message: "percher.toml failed validation — fix the file and re-run.",
+                    },
+                ],
+                reasonCode: "config_invalid",
+            });
+        case "build_failed":
+        case "missing_dependency":
+        case "health_check_timeout":
+        case "port_mismatch":
+        case "permission_denied":
+        case "runtime_crash":
+        case "oom_killed": {
+            // FUTURE1 Phase 2.3: when the API parser extracted at least one
+            // problem WITH a file location, give the agent a structured
+            // `fix_problems` recovery instead of routing through doctor.
+            // Problems without a file (missing-module by bare name,
+            // missing-build-env) are still actionable by hint but the agent
+            // has nothing to open — let doctor classify those so it can pull
+            // the build log and decide between set_env_vars / ask_user / etc.
+            const fileProblems = (failure.problems ?? []).filter((p) => p.file);
+            const reproduceAlt = failure.deployId
+                ? {
+                    action: "reproduce_locally",
+                    suggestedTool: "percher_reproduce",
+                    args: { deployId: failure.deployId, app: failure.appName },
+                    when: "after the primary path didn't surface a clear fix and the user has nixpacks installed locally",
+                }
+                : undefined;
+            if (fileProblems.length > 0) {
+                return recoveryFixProblems({
+                    problems: fileProblems.map(buildProblemToRecoveryProblem),
+                    reasonCode: "build_failed",
+                    ...(reproduceAlt
+                        ? {
+                            alternativeActions: [
+                                {
+                                    ...reproduceAlt,
+                                    when: "after fixing the file-located problems didn't make the build pass and the user has nixpacks installed locally",
+                                },
+                            ],
+                        }
+                        : {}),
+                });
+            }
+            // FUTURE12 Phase 4: route ambiguous build failures through
+            // `percher_doctor` instead of straight to `inspect_build_log`.
+            // Doctor's deploy-mode dispatch (Phase 2c) fetches the build
+            // log, runs `classifyError`, and returns a more specific
+            // recovery (`set_env_vars` when missing env keys are extracted,
+            // `fix_problems` when structured BuildProblems with file
+            // locations are extracted, falling back to `inspect_build_log`
+            // only when classification yields nothing). Publish/wait don't
+            // always have the build log when they hit this path, so handing
+            // off to doctor closes the loop with one consistent contract for
+            // agents.
+            //
+            // `inspect_build_log` is preserved as an `alternativeAction` so
+            // agents that want the raw log can still opt in after doctor's
+            // primary recovery doesn't help. Reproduce-locally chains after
+            // that for users with nixpacks installed.
+            const inspectAlt = {
+                action: "inspect_build_log",
+                suggestedTool: "percher_deploys_inspect",
+                args: failure.deployId
+                    ? { id: failure.deployId, app: failure.appName }
+                    : { latestFailed: true, app: failure.appName },
+                when: "after percher_doctor's recovery didn't yield a fix and you want to read the raw build log directly",
+            };
+            const alternativeActions = [inspectAlt];
+            if (reproduceAlt) {
+                alternativeActions.push({
+                    ...reproduceAlt,
+                    when: "after percher_doctor + percher_deploys_inspect didn't surface a clear fix and the user has nixpacks installed locally",
+                });
+            }
+            return recoveryDoctor({
+                app: failure.appName,
+                deployId: failure.deployId,
+                mode: "deploy",
+                reasonCode: "build_failed",
+                alternativeActions,
+            });
+        }
+        default:
+            // Exhaustiveness fallback. New `ErrorClass` values land here until a
+            // mapping is added — better than misclassifying as `retry`.
+            return recoveryAsk({
+                prompt: "Unexpected failure — Percher couldn't classify this error. Try `percher doctor` for diagnostics, or surface the error to the user.",
+                reasonCode: "unknown",
+            });
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

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

package/dist/stream-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cross-runtime streaming file write.
+ *
+ * Both the CLI and MCP server advertise Node.js compatibility
+ * (`npx percher`, `npx -y @percher/mcp`). The core package must not
+ * call Bun globals directly.
+ *
+ * In Bun: Bun.write(path, Response) streams to disk natively and
+ * returns the byte count — zero intermediate allocation.
+ *
+ * In Node.js 18+: we use Readable.fromWeb() + pipeline() to pipe the
+ * Web ReadableStream from the fetch Response to a fs.createWriteStream.
+ * The byte count is read back from fs.stat after the pipeline finishes.
+ */
+/**
+ * Node.js fallback — exported for direct testing so we don't need to
+ * mask the read-only Bun global in tests.
+ */
+export declare function writeResponseToFileNode(res: Response, filePath: string): Promise<number>;
+export declare function writeResponseToFile(res: Response, filePath: string): Promise<number>;
+//# sourceMappingURL=stream-utils.d.ts.map

package/dist/stream-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../src/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB9F;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1F"}

package/dist/stream-utils.js

@@ -0,0 +1,41 @@
+/**
+ * Cross-runtime streaming file write.
+ *
+ * Both the CLI and MCP server advertise Node.js compatibility
+ * (`npx percher`, `npx -y @percher/mcp`). The core package must not
+ * call Bun globals directly.
+ *
+ * In Bun: Bun.write(path, Response) streams to disk natively and
+ * returns the byte count — zero intermediate allocation.
+ *
+ * In Node.js 18+: we use Readable.fromWeb() + pipeline() to pipe the
+ * Web ReadableStream from the fetch Response to a fs.createWriteStream.
+ * The byte count is read back from fs.stat after the pipeline finishes.
+ */
+/**
+ * Node.js fallback — exported for direct testing so we don't need to
+ * mask the read-only Bun global in tests.
+ */
+export async function writeResponseToFileNode(res, filePath) {
+    if (!res.body)
+        throw new Error("Server returned empty response body");
+    const { createWriteStream } = await import("node:fs");
+    const { stat } = await import("node:fs/promises");
+    const { Readable } = await import("node:stream");
+    const { pipeline } = await import("node:stream/promises");
+    const fileStream = createWriteStream(filePath);
+    // fromWeb converts a WHATWG ReadableStream to a Node.js Readable.
+    // The cast is needed because TypeScript's Node typedefs require
+    // stream.web.ReadableStream but fetch returns the global ReadableStream.
+    const nodeReadable = Readable.fromWeb(res.body);
+    await pipeline(nodeReadable, fileStream);
+    const { size } = await stat(filePath);
+    return size;
+}
+export async function writeResponseToFile(res, filePath) {
+    if (typeof Bun !== "undefined") {
+        return Bun.write(filePath, res);
+    }
+    return writeResponseToFileNode(res, filePath);
+}
+//# sourceMappingURL=stream-utils.js.map

package/dist/stream-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.js","sourceRoot":"","sources":["../src/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,GAAa,EAAE,QAAgB;IAC3E,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAEtE,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAClD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACjD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAE1D,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,kEAAkE;IAClE,gEAAgE;IAChE,yEAAyE;IACzE,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CACnC,GAAG,CAAC,IAAyD,CAC9D,CAAC;IACF,MAAM,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAa,EAAE,QAAgB;IACvE,IAAI,OAAO,GAAG,KAAK,WAAW,EAAE,CAAC;QAC/B,OAAQ,GAAyE,CAAC,KAAK,CACrF,QAAQ,EACR,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO,uBAAuB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC"}

package/dist/templates/ai-files/claude-md.d.ts

@@ -0,0 +1,7 @@
+export declare const CLAUDE_MD: {
+    id: "claude-md";
+    path: string;
+    version: string;
+    content: string;
+};
+//# sourceMappingURL=claude-md.d.ts.map

package/dist/templates/ai-files/claude-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../../../src/templates/ai-files/claude-md.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;CA4ErB,CAAC"}

package/dist/templates/ai-files/claude-md.js

@@ -0,0 +1,78 @@
+export const CLAUDE_MD = {
+    id: "claude-md",
+    path: "CLAUDE.md",
+    version: "1.0.0",
+    content: `# CLAUDE.md — Percher publishing instructions
+
+This project is hosted on **Percher** (https://percher.app). Apps run
+at \`<name>.percher.run\`.
+
+## Publishing
+
+\`\`\`bash
+bunx percher publish
+\`\`\`
+
+This single command:
+- Auto-generates \`percher.toml\` if missing
+- Logs in via device-code if not already authenticated
+- Packages, uploads, builds, deploys
+- Returns the live URL
+
+## Setting secrets
+
+Never put secret values in \`percher.toml\` or anywhere in source.
+
+\`\`\`bash
+# from a file:
+bunx percher env set DATABASE_URL --from-file ./secret.txt
+
+# from stdin (CI / scripts):
+echo "$MY_SECRET" | bunx percher env set DATABASE_URL --from-stdin
+
+# interactive (you type, no echo):
+bunx percher env set DATABASE_URL
+\`\`\`
+
+## Daily commands
+
+| Command                          | What it does                                  |
+| -------------------------------- | --------------------------------------------- |
+| \`bunx percher publish\`         | Build + deploy this project.                  |
+| \`bunx percher dev\`             | Watch files, redeploy on change, stream logs. |
+| \`bunx percher logs\`            | Tail runtime logs.                            |
+| \`bunx percher logs --build\`    | Show last failed build's full log.            |
+| \`bunx percher deploys\`         | List recent deploys with status.              |
+| \`bunx percher rollback <sha>\`  | Roll back to a previous version.              |
+| \`bunx percher doctor\`          | Diagnose config / connectivity.               |
+| \`bunx percher env list\`        | Show env vars (values masked).                |
+
+## MCP
+
+For MCP-aware editors (Claude Code, Cursor, Windsurf), run
+\`bunx percher mcp\` to print a paste-ready config block.
+
+## When the build fails
+
+Don't guess. Run:
+
+\`\`\`bash
+bunx percher logs --build
+\`\`\`
+
+The output ends with the actual compiler/builder error. Show it back,
+fix the root cause, and retry.
+
+## Don'ts
+
+- Don't add \`percher.toml\` fields not in the documented schema.
+- Don't commit secrets — use \`percher env set\`.
+- Don't use \`--no-verify\` or other bypass flags on git operations.
+- Don't \`rm -rf\` the \`.percher/\` directory — it tracks managed
+  AI-files. Use \`bunx percher ai-files remove\` instead.
+
+This file is managed by \`bunx percher ai-files\`. Run
+\`bunx percher ai-files update\` to pull updates.
+`,
+};
+//# sourceMappingURL=claude-md.js.map

package/dist/templates/ai-files/claude-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.js","sourceRoot":"","sources":["../../../src/templates/ai-files/claude-md.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,WAAoB;IACxB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,OAAO;IAChB,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEV;CACA,CAAC"}

package/dist/templates/ai-files/cursor-percher-mdc.d.ts

@@ -0,0 +1,7 @@
+export declare const CURSOR_PERCHER_MDC: {
+    id: "cursor-percher-mdc";
+    path: string;
+    version: string;
+    content: string;
+};
+//# sourceMappingURL=cursor-percher-mdc.d.ts.map

package/dist/templates/ai-files/cursor-percher-mdc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-percher-mdc.d.ts","sourceRoot":"","sources":["../../../src/templates/ai-files/cursor-percher-mdc.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;;;;CA6G9B,CAAC"}

package/dist/templates/ai-files/cursor-percher-mdc.js

@@ -0,0 +1,111 @@
+export const CURSOR_PERCHER_MDC = {
+    id: "cursor-percher-mdc",
+    path: ".cursor/rules/percher.mdc",
+    version: "1.0.0",
+    content: `---
+description: How to publish this project to Percher
+globs: ["percher.toml", "**/*.{ts,tsx,js,jsx,py}"]
+alwaysApply: false
+---
+
+# Publishing to Percher
+
+Percher hosts AI-built web apps. The user says "publish my app" → it's
+live at \`name.percher.run\`.
+
+## Quick reference
+
+- **CLI:** \`bunx percher\` (or \`npx percher\`)
+- **Config:** \`percher.toml\` in project root
+- **Deploy:** \`bunx percher publish\` — handles auth, config, build, deploy
+- **Dashboard:** https://percher.app
+
+## Before deploying
+
+1. Check \`percher.toml\` exists. If not, run \`bunx percher init\` (or just
+   run \`publish\` — it auto-generates one).
+2. Make sure secrets are set: \`bunx percher env set KEY --from-stdin\`
+   (or \`KEY=VALUE\` for non-secrets).
+3. For secrets, never use \`KEY=VALUE\` — use \`--from-stdin\`,
+   \`--from-file <path>\`, or bare \`KEY\` (interactive prompt).
+
+## Common percher.toml shapes
+
+\`\`\`toml
+# Next.js
+[app]
+name = "my-app"
+runtime = "node"
+framework = "nextjs"
+[build]
+command = "bun run build"
+output = ".next"
+[web]
+port = 3000
+health = "/api/health"
+[data]
+mode = "pocketbase"
+\`\`\`
+
+\`\`\`toml
+# Static (Vite, plain HTML)
+[app]
+name = "my-app"
+runtime = "static"
+[build]
+command = "bun run build"
+output = "dist"
+\`\`\`
+
+## Build-time public env vars
+
+Frameworks like Next/Vite/Astro bake \`*_PUBLIC_*\` values into the bundle
+at build time. Vars matching the public-prefix conventions
+(\`NEXT_PUBLIC_*\`, \`VITE_*\`, \`PUBLIC_*\`, \`REACT_APP_*\`, \`VUE_APP_*\`,
+\`EXPO_PUBLIC_*\`) auto-forward to the build container — just \`bunx percher
+env set NEXT_PUBLIC_API_URL=…\` and it lands in the bundle on the next
+deploy. No TOML changes needed.
+
+Server-secret build tokens that DON'T match a prefix (Sentry source-map
+upload, private npm registries) require explicit opt-in:
+
+\`\`\`toml
+[build]
+pass_env = ["SENTRY_AUTH_TOKEN", "NPM_TOKEN"]
+\`\`\`
+
+Values still come from \`bunx percher env set …\`; the TOML only declares
+which non-prefix keys leak into the build.
+
+## Outbound HTTPS
+
+Apps reach the public internet through a forward proxy. Bun's \`fetch\`
+and Node 24+ \`fetch\` (with \`NODE_USE_ENV_PROXY=1\`, set automatically)
+honor it. Node ≤22 needs:
+
+\`\`\`ts
+import { ProxyAgent, setGlobalDispatcher } from "undici";
+if (process.env.HTTPS_PROXY) {
+  setGlobalDispatcher(new ProxyAgent(process.env.HTTPS_PROXY));
+}
+\`\`\`
+
+## When something fails
+
+- \`bunx percher logs\` — runtime logs
+- \`bunx percher logs --build\` — last failed build's log
+- \`bunx percher doctor\` — connectivity + config check
+- \`bunx percher deploys --limit 5\` — recent deploys + status
+
+## Rules
+
+1. Never put real secrets in \`percher.toml\`. Use \`bunx percher env set\`.
+2. Never invent \`percher.toml\` fields. Stick to documented schema.
+3. Always add a \`/health\` endpoint when the framework has a server.
+4. \`percher.toml\` is the source of truth — read from it, don't guess.
+
+This file is managed by \`bunx percher ai-files\`. Run
+\`bunx percher ai-files update\` to pull updates.
+`,
+};
+//# sourceMappingURL=cursor-percher-mdc.js.map

package/dist/templates/ai-files/cursor-percher-mdc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-percher-mdc.js","sourceRoot":"","sources":["../../../src/templates/ai-files/cursor-percher-mdc.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,EAAE,EAAE,oBAA6B;IACjC,IAAI,EAAE,2BAA2B;IACjC,OAAO,EAAE,OAAO;IAChB,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwGV;CACA,CAAC"}

package/dist/templates/ai-files/index.d.ts

@@ -0,0 +1,8 @@
+export interface AiFileTemplate {
+    id: string;
+    path: string;
+    version: string;
+    content: string;
+}
+export declare const AI_FILE_TEMPLATES: readonly AiFileTemplate[];
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/ai-files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/ai-files/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAAoC,CAAC"}

package/dist/templates/ai-files/index.js

@@ -0,0 +1,4 @@
+import { CLAUDE_MD } from "./claude-md";
+import { CURSOR_PERCHER_MDC } from "./cursor-percher-mdc";
+export const AI_FILE_TEMPLATES = [CLAUDE_MD, CURSOR_PERCHER_MDC];
+//# sourceMappingURL=index.js.map

package/dist/templates/ai-files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/ai-files/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAS1D,MAAM,CAAC,MAAM,iBAAiB,GAA8B,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percher/core",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Core logic and CLI commands for the Percher hosting platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,11 +29,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@percher/client": "^0.2.0",
-    "@percher/toml": "^0.1.1",
-    "ignore": "^6.0.2",
+    "@percher/client": "^0.2.7",
+    "@percher/toml": "^0.1.3",
+    "ignore": "^7.0.5",
     "tar-stream": "^3.1.7",
-    "zod": "^3.23.8"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/tar-stream": "^3.1.3",