@solcreek/cli 0.4.21 → 0.4.22

package/dist/utils/creekd-client.js

@@ -0,0 +1,144 @@
+/**
+ * Lightweight creekd admin API client for the CLI.
+ *
+ * Uses plain fetch (no openapi-fetch dep) with types matching
+ * the OpenAPI spec. The CLI only needs a handful of endpoints.
+ */
+export class CreekdApiError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`creekd: ${code} (${status})`);
+        this.status = status;
+        this.code = code;
+        this.name = "CreekdApiError";
+    }
+}
+/**
+ * Thrown specifically on 412 Precondition Failed (If-Match
+ * mismatch). Carries the daemon's CURRENT rv so the caller can
+ * decide between (a) prompting the user to refresh, (b) auto-
+ * retrying with the fresh rv when --bypass-rv was passed, or
+ * (c) emitting a structured machine-readable error to JSON mode.
+ *
+ * Per DESIGN-self-host-state.md §"First-party CLI MUST send
+ * If-Match": "On 412, CLI surfaces a structured prompt and does
+ * NOT auto-retry by default."
+ */
+export class CreekdResourceVersionMismatchError extends CreekdApiError {
+    currentResourceVersion;
+    attemptedResourceVersion;
+    constructor(currentResourceVersion, attemptedResourceVersion) {
+        super(412, "resource_version_mismatch");
+        this.currentResourceVersion = currentResourceVersion;
+        this.attemptedResourceVersion = attemptedResourceVersion;
+        this.name = "CreekdResourceVersionMismatchError";
+        this.message = `creekd: resource_version_mismatch (current=${currentResourceVersion}, attempted=${attemptedResourceVersion})`;
+    }
+}
+const DEFAULT_URL = "http://127.0.0.1:9080";
+export function getCreekdUrl() {
+    return process.env.CREEKD_URL || process.env.CREEKCTL_SERVER || DEFAULT_URL;
+}
+export function getCreekdToken() {
+    return process.env.CREEKD_TOKEN || process.env.CREEKCTL_TOKEN || "";
+}
+export class CreekdClient {
+    token;
+    baseUrl;
+    constructor(baseUrl = getCreekdUrl(), token = getCreekdToken()) {
+        this.token = token;
+        // Normalise: add http:// for bare host:port. Mirrors
+        // utils/hostkey.ts's normalizeAdminAddr so the two callers
+        // accept the same shape from hosts.json.
+        if (!/^https?:\/\//.test(baseUrl)) {
+            baseUrl = "http://" + baseUrl;
+        }
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    async listApps() {
+        const resp = await this.get("/v1/apps");
+        return resp.apps;
+    }
+    async getApp(id) {
+        return this.get(`/v1/apps/${encodeURIComponent(id)}`);
+    }
+    async getStats(id) {
+        return this.get(`/v1/apps/${encodeURIComponent(id)}/stats`);
+    }
+    async getAppLogs(id, tail = 100) {
+        const res = await this.request("GET", `/v1/apps/${encodeURIComponent(id)}/logs?tail=${tail}`);
+        return res.text();
+    }
+    async stopApp(id, opts = {}) {
+        await this.request("DELETE", `/v1/apps/${encodeURIComponent(id)}`, undefined, opts.ifMatch);
+    }
+    /**
+     * Spawn a brand-new app. POST /v1/apps. Creation is not
+     * spec-mutating in the rv sense — there's no prior version to
+     * If-Match against — so ifMatch is intentionally NOT a parameter.
+     */
+    async spawnApp(body) {
+        return this.post(`/v1/apps`, body);
+    }
+    /**
+     * Blue-green deploy of an existing app. POST /v1/apps/{id}/deploy.
+     * Spec-mutating; pass ifMatch sourced from the local cache (or a
+     * fresh getApp) — 412 surfaces as CreekdResourceVersionMismatchError.
+     */
+    async deployApp(id, body, opts = {}) {
+        const res = await this.request("POST", `/v1/apps/${encodeURIComponent(id)}/deploy`, body, opts.ifMatch);
+        return res.json();
+    }
+    async restartApp(id) {
+        // Restart is an OPERATION, not a spec mutation per
+        // DESIGN-self-host-state.md §"Mutex granularity" — supervisor
+        // restarts an existing app in place, neither generation nor rv
+        // bumps. No If-Match needed.
+        return this.post(`/v1/apps/${encodeURIComponent(id)}/restart`, {});
+    }
+    /**
+     * Roll back to the target release seq. Spec-mutating — accepts
+     * If-Match. Throws CreekdResourceVersionMismatchError on 412.
+     */
+    async rollbackApp(id, toSeq, opts = {}) {
+        const path = `/v1/apps/${encodeURIComponent(id)}/rollback?to=${toSeq}`;
+        const res = await this.request("POST", path, undefined, opts.ifMatch);
+        return res.json();
+    }
+    async get(path) {
+        const res = await this.request("GET", path);
+        return res.json();
+    }
+    async post(path, body) {
+        const res = await this.request("POST", path, body);
+        return res.json();
+    }
+    async request(method, path, body, ifMatch) {
+        const headers = {};
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (ifMatch !== undefined)
+            headers["If-Match"] = ifMatch;
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ code: "unknown", error: res.statusText }));
+            // 412 carries the daemon's current rv in the body so the
+            // caller can decide whether to refresh + retry. Surface as
+            // the typed subclass — generic error handlers still catch it
+            // via instanceof CreekdApiError.
+            if (res.status === 412 && err.code === "resource_version_mismatch") {
+                throw new CreekdResourceVersionMismatchError(err.currentResourceVersion ?? "", ifMatch ?? "");
+            }
+            throw new CreekdApiError(res.status, err.code);
+        }
+        return res;
+    }
+}
+//# sourceMappingURL=creekd-client.js.map

package/dist/utils/gitignore.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureGitignoreEntries(dir: string): void;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/utils/gitignore.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+const ENTRIES = [
+    ".creek",
+    ".agent",
+    ".agents",
+    ".augment",
+    ".claude",
+    ".cline",
+    ".cursor",
+    ".github/copilot*",
+    ".kilocode",
+    ".kiro",
+    ".qoder",
+    ".qwen",
+    ".roo",
+    ".trae",
+    ".windsurf",
+];
+export function ensureGitignoreEntries(dir) {
+    const gitignorePath = join(dir, ".gitignore");
+    const existing = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, "utf-8")
+        : "";
+    const lines = new Set(existing.split("\n").map((l) => l.trim()));
+    const missing = ENTRIES.filter((entry) => !lines.has(entry));
+    if (!missing.length)
+        return;
+    const block = `\n# Creek & AI agent configs\n${missing.join("\n")}\n`;
+    appendFileSync(gitignorePath, block);
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/utils/hostkey.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TOFU hostkey discovery — call creekd's GET /v1/hostkey
+ * (unauthenticated, exposes the daemon's ed25519 pubkey +
+ * fingerprint per DESIGN §"TOFU hostkey discovery") and verify the
+ * response shape.
+ *
+ * The fingerprint is what the operator should verify out-of-band
+ * before pinning (Path B / C in DESIGN). This module is the
+ * transport layer; the init command wraps it with the prompt UX.
+ */
+/** Wire shape returned by GET /v1/hostkey. */
+export interface HostkeyInfo {
+    algorithm: "ed25519";
+    publicKey: string;
+    fingerprint: string;
+}
+/** Thrown when the daemon's response is malformed. */
+export declare class HostkeyResponseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fetch the host key from a creekd daemon. addr may be a bare
+ * host:port (the function adds the `http://` scheme) or a full URL.
+ */
+export declare function fetchHostkey(addr: string, fetchImpl?: typeof fetch): Promise<HostkeyInfo>;
+/** Throws if body is missing fields or has wrong types. */
+export declare function validateHostkey(body: Partial<HostkeyInfo>): HostkeyInfo;
+/** Compute sha256(base64-decoded publicKey) in "sha256:<hex>" form. */
+export declare function computeFingerprint(publicKeyBase64: string): string;
+/**
+ * Validate a Path C fingerprint string operator-pasted from the
+ * provider console / paper bundle. Accepts the canonical form
+ * "sha256:<64 hex chars>". Returns the canonical lowercased form
+ * or throws.
+ */
+export declare function parsePastedFingerprint(input: string): string;
+/** Add http:// if scheme is missing. Reject https for 0.0.x (admin is loopback / Caddy-fronted; daemon itself speaks plain HTTP). */
+export declare function normalizeAdminAddr(addr: string): string;
+//# sourceMappingURL=hostkey.d.ts.map

package/dist/utils/hostkey.js

@@ -0,0 +1,84 @@
+/**
+ * TOFU hostkey discovery — call creekd's GET /v1/hostkey
+ * (unauthenticated, exposes the daemon's ed25519 pubkey +
+ * fingerprint per DESIGN §"TOFU hostkey discovery") and verify the
+ * response shape.
+ *
+ * The fingerprint is what the operator should verify out-of-band
+ * before pinning (Path B / C in DESIGN). This module is the
+ * transport layer; the init command wraps it with the prompt UX.
+ */
+import { createHash } from "node:crypto";
+/** Thrown when the daemon's response is malformed. */
+export class HostkeyResponseError extends Error {
+    constructor(message) {
+        super(`hostkey: ${message}`);
+        this.name = "HostkeyResponseError";
+    }
+}
+/**
+ * Fetch the host key from a creekd daemon. addr may be a bare
+ * host:port (the function adds the `http://` scheme) or a full URL.
+ */
+export async function fetchHostkey(addr, fetchImpl = fetch) {
+    const url = normalizeAdminAddr(addr) + "/v1/hostkey";
+    const resp = await fetchImpl(url);
+    if (!resp.ok) {
+        if (resp.status === 503) {
+            throw new HostkeyResponseError(`daemon at ${addr} returned 503 — hostkey not yet initialised`);
+        }
+        throw new HostkeyResponseError(`daemon at ${addr} returned ${resp.status}`);
+    }
+    const body = (await resp.json());
+    return validateHostkey(body);
+}
+/** Throws if body is missing fields or has wrong types. */
+export function validateHostkey(body) {
+    if (body.algorithm !== "ed25519") {
+        throw new HostkeyResponseError(`unknown algorithm "${String(body.algorithm)}"`);
+    }
+    if (typeof body.publicKey !== "string" || body.publicKey.length === 0) {
+        throw new HostkeyResponseError("missing publicKey");
+    }
+    if (typeof body.fingerprint !== "string" || !body.fingerprint.startsWith("sha256:")) {
+        throw new HostkeyResponseError(`malformed fingerprint "${String(body.fingerprint)}"`);
+    }
+    // Independent fingerprint check — recompute from publicKey, compare
+    // to what the daemon claims. Prevents the daemon (or a MITM) from
+    // claiming a fingerprint that doesn't match the bytes it just
+    // returned. If THIS fails, the daemon is buggy or actively
+    // adversarial; either way we should not pin.
+    const recomputed = computeFingerprint(body.publicKey);
+    if (recomputed !== body.fingerprint) {
+        throw new HostkeyResponseError(`fingerprint ${body.fingerprint} does not match sha256(publicKey) ${recomputed}`);
+    }
+    return body;
+}
+/** Compute sha256(base64-decoded publicKey) in "sha256:<hex>" form. */
+export function computeFingerprint(publicKeyBase64) {
+    const bytes = Buffer.from(publicKeyBase64, "base64");
+    const hex = createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+}
+/**
+ * Validate a Path C fingerprint string operator-pasted from the
+ * provider console / paper bundle. Accepts the canonical form
+ * "sha256:<64 hex chars>". Returns the canonical lowercased form
+ * or throws.
+ */
+export function parsePastedFingerprint(input) {
+    const trimmed = input.trim();
+    const match = /^sha256:([0-9a-fA-F]{64})$/.exec(trimmed);
+    if (!match) {
+        throw new HostkeyResponseError(`paste must be "sha256:<64 hex chars>"; got "${trimmed.slice(0, 40)}${trimmed.length > 40 ? "…" : ""}"`);
+    }
+    return `sha256:${match[1].toLowerCase()}`;
+}
+/** Add http:// if scheme is missing. Reject https for 0.0.x (admin is loopback / Caddy-fronted; daemon itself speaks plain HTTP). */
+export function normalizeAdminAddr(addr) {
+    if (addr.startsWith("http://") || addr.startsWith("https://")) {
+        return addr.replace(/\/+$/, "");
+    }
+    return "http://" + addr.replace(/\/+$/, "");
+}
+//# sourceMappingURL=hostkey.js.map

package/dist/utils/hosts.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Laptop-side multi-host registry. Schema per DESIGN-self-host-state.md
+ * §"Multi-host CLI state":
+ *
+ *   ~/.creek/hosts.json
+ *   {
+ *     "schemaVersion": 1,
+ *     "fleetLabel": "...",
+ *     "hosts": [{ name, id, ip, creekdPubkey, ... }]
+ *   }
+ *
+ * 0.0.x ships only the fields needed for TOFU hostkey pinning
+ * (name, addr, creekdPubkey + fingerprint, lastSeen). The optional
+ * agePubkey / provider / sshKeyFingerprint / region fields land in
+ * 0.1.0 when the recovery kit + capstan provisioning paths arrive.
+ *
+ * Writes are atomic via tmp + rename (DESIGN line 550). flock is
+ * deferred — 0.0.x is single-user dogfood; concurrent writers from
+ * the same laptop are not yet a concern.
+ */
+export declare const HOSTS_SCHEMA_VERSION = 1;
+/** One pinned creekd host entry. */
+export interface HostEntry {
+    /** Operator-chosen short name. Unique within the file. */
+    name: string;
+    /** addr is host:port or just host. Where the admin API listens. */
+    addr: string;
+    /** ed25519 public key bytes, base64-encoded. From GET /v1/hostkey. */
+    creekdPubkey: string;
+    /** "sha256:<hex>" of the pubkey bytes — what the operator pastes / verifies. */
+    fingerprint: string;
+    /** RFC3339 timestamp of last successful contact. Updated on each verify. */
+    lastSeen: string;
+    /** Optional 0.0.x — populated in 0.1.0 by the recovery-kit flow. */
+    agePubkey?: string;
+}
+/** Top-level shape of ~/.creek/hosts.json. */
+export interface HostsFile {
+    schemaVersion: number;
+    /** Operator-chosen label for the whole fleet. Optional. */
+    fleetLabel?: string;
+    hosts: HostEntry[];
+}
+/** Resolve ~/.creek/hosts.json. Exposed so tests can override via env. */
+export declare function hostsPath(): string;
+/** Read hosts.json. Returns an empty file shape if absent. */
+export declare function readHosts(path?: string): HostsFile;
+/**
+ * Write hosts.json atomically — write to <path>.tmp, then rename
+ * over the destination. The rename is atomic on POSIX filesystems;
+ * a reader sees either the old file or the new file, never a
+ * half-written one. Crash during write leaves the tmp behind but
+ * never corrupts hosts.json itself.
+ */
+export declare function writeHosts(file: HostsFile, path?: string): void;
+/**
+ * Insert or replace a host by name. Returns a new HostsFile —
+ * does not mutate the input. Pure so it's trivially testable.
+ *
+ * Replacement semantics: same `name` overwrites. Same fingerprint
+ * with a different name is allowed (operator may legitimately
+ * register the same host under two labels). Re-pinning with a
+ * NEW fingerprint for an existing name is a TOFU rotation — the
+ * caller is responsible for confirming this is intentional; the
+ * util just records it.
+ */
+export declare function upsertHost(file: HostsFile, entry: HostEntry): HostsFile;
+/** Find a host by name. */
+export declare function findHost(file: HostsFile, name: string): HostEntry | undefined;
+//# sourceMappingURL=hosts.d.ts.map

package/dist/utils/hosts.js

@@ -0,0 +1,90 @@
+/**
+ * Laptop-side multi-host registry. Schema per DESIGN-self-host-state.md
+ * §"Multi-host CLI state":
+ *
+ *   ~/.creek/hosts.json
+ *   {
+ *     "schemaVersion": 1,
+ *     "fleetLabel": "...",
+ *     "hosts": [{ name, id, ip, creekdPubkey, ... }]
+ *   }
+ *
+ * 0.0.x ships only the fields needed for TOFU hostkey pinning
+ * (name, addr, creekdPubkey + fingerprint, lastSeen). The optional
+ * agePubkey / provider / sshKeyFingerprint / region fields land in
+ * 0.1.0 when the recovery kit + capstan provisioning paths arrive.
+ *
+ * Writes are atomic via tmp + rename (DESIGN line 550). flock is
+ * deferred — 0.0.x is single-user dogfood; concurrent writers from
+ * the same laptop are not yet a concern.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const HOSTS_SCHEMA_VERSION = 1;
+/** Resolve ~/.creek/hosts.json. Exposed so tests can override via env. */
+export function hostsPath() {
+    return process.env.CREEK_HOSTS_PATH ?? join(homedir(), ".creek", "hosts.json");
+}
+/** Read hosts.json. Returns an empty file shape if absent. */
+export function readHosts(path = hostsPath()) {
+    if (!existsSync(path)) {
+        return { schemaVersion: HOSTS_SCHEMA_VERSION, hosts: [] };
+    }
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.schemaVersion !== "number") {
+        throw new Error(`hosts.json: missing schemaVersion`);
+    }
+    if (parsed.schemaVersion !== HOSTS_SCHEMA_VERSION) {
+        throw new Error(`hosts.json: unsupported schemaVersion ${parsed.schemaVersion} ` +
+            `(want ${HOSTS_SCHEMA_VERSION})`);
+    }
+    if (!Array.isArray(parsed.hosts)) {
+        throw new Error(`hosts.json: hosts is not an array`);
+    }
+    return parsed;
+}
+/**
+ * Write hosts.json atomically — write to <path>.tmp, then rename
+ * over the destination. The rename is atomic on POSIX filesystems;
+ * a reader sees either the old file or the new file, never a
+ * half-written one. Crash during write leaves the tmp behind but
+ * never corrupts hosts.json itself.
+ */
+export function writeHosts(file, path = hostsPath()) {
+    if (file.schemaVersion !== HOSTS_SCHEMA_VERSION) {
+        throw new Error(`writeHosts: schemaVersion ${file.schemaVersion} != ${HOSTS_SCHEMA_VERSION}`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/**
+ * Insert or replace a host by name. Returns a new HostsFile —
+ * does not mutate the input. Pure so it's trivially testable.
+ *
+ * Replacement semantics: same `name` overwrites. Same fingerprint
+ * with a different name is allowed (operator may legitimately
+ * register the same host under two labels). Re-pinning with a
+ * NEW fingerprint for an existing name is a TOFU rotation — the
+ * caller is responsible for confirming this is intentional; the
+ * util just records it.
+ */
+export function upsertHost(file, entry) {
+    const idx = file.hosts.findIndex((h) => h.name === entry.name);
+    const next = file.hosts.slice();
+    if (idx >= 0) {
+        next[idx] = entry;
+    }
+    else {
+        next.push(entry);
+    }
+    return { ...file, hosts: next };
+}
+/** Find a host by name. */
+export function findHost(file, name) {
+    return file.hosts.find((h) => h.name === name);
+}
+//# sourceMappingURL=hosts.js.map

package/dist/utils/local-cache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Project-local cache of the laptop's view of creekd's state.
+ *
+ * Lives at `<project>/.creek/local.json` and is the canonical
+ * source for the `If-Match` header per DESIGN-self-host-state.md
+ * §"First-party CLI MUST send If-Match" (line 230-232):
+ *
+ *   "The creek CLI ... MUST send If-Match on every mutating call,
+ *    sourced from .creek/local.json.lastDeploy.resourceVersion."
+ *
+ * Schema is intentionally narrow in 0.0.x:
+ *   {
+ *     "schemaVersion": 1,
+ *     "lastDeploy": {
+ *       "appId": "...",
+ *       "host": "...",       // hosts.json name; "" for default loopback
+ *       "resourceVersion": "<opaque>",
+ *       "generation": <int>,
+ *       "at": "RFC3339"
+ *     }
+ *   }
+ *
+ * Writes are atomic (tmp + rename) to match the hosts.json
+ * convention; corrupt-then-crash leaves the file untouched.
+ *
+ * NOTE: this is per-project state, NOT per-host. Multi-host
+ * deploys of the same project use a single lastDeploy slot —
+ * switching --host between deploys invalidates the cache and
+ * triggers a fresh GET to re-seed. This is intentional: the cache
+ * is a hot path optimisation, not authoritative — the daemon's
+ * current rv is always the truth.
+ */
+export declare const LOCAL_SCHEMA_VERSION = 1;
+/** Snapshot of the last successful spec-mutation against creekd. */
+export interface LastDeploy {
+    appId: string;
+    /** hosts.json `name` if any was used; empty string for default localhost. */
+    host: string;
+    /** Opaque rv string from the wire — clients MUST NOT do arithmetic on it. */
+    resourceVersion: string;
+    /** Generation as of last successful deploy (sanity check). */
+    generation: number;
+    /** RFC3339 timestamp of the write. */
+    at: string;
+}
+export interface LocalCacheFile {
+    schemaVersion: number;
+    lastDeploy?: LastDeploy;
+}
+/** Resolve <project>/.creek/local.json. */
+export declare function localCachePath(projectRoot: string): string;
+/** Read the cache. Returns an empty file shape if absent. */
+export declare function readLocalCache(projectRoot: string): LocalCacheFile;
+/** Atomic write — tmp + rename. */
+export declare function writeLocalCache(projectRoot: string, file: LocalCacheFile): void;
+/**
+ * Update lastDeploy after a successful spec mutation. Reads the
+ * existing file, replaces lastDeploy, writes back. Convenience
+ * wrapper for the most common write pattern.
+ */
+export declare function recordLastDeploy(projectRoot: string, lastDeploy: LastDeploy): void;
+/**
+ * Read the cached rv for an If-Match header. Returns undefined
+ * when the cache is empty, when the appId/host don't match
+ * (different project or host than last deploy), or when the cache
+ * is corrupt. Callers fall back to a fresh GET on undefined.
+ */
+export declare function cachedResourceVersion(projectRoot: string, appId: string, host: string): string | undefined;
+//# sourceMappingURL=local-cache.d.ts.map

package/dist/utils/local-cache.js

@@ -0,0 +1,100 @@
+/**
+ * Project-local cache of the laptop's view of creekd's state.
+ *
+ * Lives at `<project>/.creek/local.json` and is the canonical
+ * source for the `If-Match` header per DESIGN-self-host-state.md
+ * §"First-party CLI MUST send If-Match" (line 230-232):
+ *
+ *   "The creek CLI ... MUST send If-Match on every mutating call,
+ *    sourced from .creek/local.json.lastDeploy.resourceVersion."
+ *
+ * Schema is intentionally narrow in 0.0.x:
+ *   {
+ *     "schemaVersion": 1,
+ *     "lastDeploy": {
+ *       "appId": "...",
+ *       "host": "...",       // hosts.json name; "" for default loopback
+ *       "resourceVersion": "<opaque>",
+ *       "generation": <int>,
+ *       "at": "RFC3339"
+ *     }
+ *   }
+ *
+ * Writes are atomic (tmp + rename) to match the hosts.json
+ * convention; corrupt-then-crash leaves the file untouched.
+ *
+ * NOTE: this is per-project state, NOT per-host. Multi-host
+ * deploys of the same project use a single lastDeploy slot —
+ * switching --host between deploys invalidates the cache and
+ * triggers a fresh GET to re-seed. This is intentional: the cache
+ * is a hot path optimisation, not authoritative — the daemon's
+ * current rv is always the truth.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const LOCAL_SCHEMA_VERSION = 1;
+/** Resolve <project>/.creek/local.json. */
+export function localCachePath(projectRoot) {
+    return join(projectRoot, ".creek", "local.json");
+}
+/** Read the cache. Returns an empty file shape if absent. */
+export function readLocalCache(projectRoot) {
+    const path = localCachePath(projectRoot);
+    if (!existsSync(path)) {
+        return { schemaVersion: LOCAL_SCHEMA_VERSION };
+    }
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.schemaVersion !== "number") {
+        throw new Error(`local.json: missing schemaVersion`);
+    }
+    if (parsed.schemaVersion !== LOCAL_SCHEMA_VERSION) {
+        throw new Error(`local.json: unsupported schemaVersion ${parsed.schemaVersion} ` +
+            `(want ${LOCAL_SCHEMA_VERSION})`);
+    }
+    return parsed;
+}
+/** Atomic write — tmp + rename. */
+export function writeLocalCache(projectRoot, file) {
+    if (file.schemaVersion !== LOCAL_SCHEMA_VERSION) {
+        throw new Error(`writeLocalCache: schemaVersion ${file.schemaVersion} != ${LOCAL_SCHEMA_VERSION}`);
+    }
+    const path = localCachePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/**
+ * Update lastDeploy after a successful spec mutation. Reads the
+ * existing file, replaces lastDeploy, writes back. Convenience
+ * wrapper for the most common write pattern.
+ */
+export function recordLastDeploy(projectRoot, lastDeploy) {
+    const file = readLocalCache(projectRoot);
+    writeLocalCache(projectRoot, { ...file, lastDeploy });
+}
+/**
+ * Read the cached rv for an If-Match header. Returns undefined
+ * when the cache is empty, when the appId/host don't match
+ * (different project or host than last deploy), or when the cache
+ * is corrupt. Callers fall back to a fresh GET on undefined.
+ */
+export function cachedResourceVersion(projectRoot, appId, host) {
+    let file;
+    try {
+        file = readLocalCache(projectRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const last = file.lastDeploy;
+    if (!last)
+        return undefined;
+    if (last.appId !== appId)
+        return undefined;
+    if (last.host !== host)
+        return undefined;
+    return last.resourceVersion;
+}
+//# sourceMappingURL=local-cache.js.map

package/dist/utils/nextjs.d.ts

@@ -15,8 +15,10 @@ export declare function getNextVersion(cwd: string): string | null;
 /**
  * Unified Next.js build entry point.
  *
- * - Next.js >= 16.2.3: Creek adapter path (recommended)
- * - Next.js < 16.2.3: legacy opennext path (best effort)
+ * - Next.js >= 16.2.3: Creek adapter path (recommended). The adapter is
+ *   lazily installed into .creek/node_modules on first use — the CLI never
+ *   depends on it directly, so non-Next.js users never pay for it.
+ * - Next.js < 16.2.3 (or adapter install fails): legacy opennext path.
  *
  * Min version for the adapter path matches @solcreek/adapter-creek's
  * peerDependency, which pins Next.js >= 16.2.3 to fix CVE-2026-23869.