@kya-os/cli 1.7.0 → 2.0.0

package/dist/utils/checkpoint-api.d.ts

@@ -0,0 +1,86 @@
+/**
+ * HTTP client for the `kya-os checkpoint init` claim-token flow (KYA-1037).
+ *
+ * Talks to the three public Checkpoint dashboard endpoints added for this
+ * flow: register a claim token, poll its status, and exchange a claimed
+ * token for a project API key. Base URL is `CHECKPOINT_API_URL` when set,
+ * else the production dashboard origin, mirroring the `KTA_API_URL` /
+ * `KTA_BASE_URL` override pattern already used by `register.ts`/`claim.ts`
+ * for the sibling knowthat.ai claim flow.
+ */
+/**
+ * Reconstructs the claim URL from a token alone, same shape the register
+ * endpoint itself builds (`/cli/claim?token=...` off the same base). Used
+ * only as a fallback for a marker written before this CLI persisted the
+ * server-issued `claimUrl` directly; a current run always reprints the
+ * value the server returned at register time.
+ */
+export declare function buildCheckpointClaimUrl(claimToken: string): string;
+/** The configured Checkpoint origin (protocol + host), to host-match a server-returned URL before acting on it. */
+export declare function checkpointOrigin(): string;
+/**
+ * True when CHECKPOINT_API_URL resolves to plain http on a non-localhost
+ * host: the claim token, and later the minted API key, cross that
+ * connection in the clear.
+ */
+export declare function isInsecureCheckpointOrigin(): boolean;
+export interface CheckpointRegisterHints {
+    domainHint?: string;
+    repoName?: string;
+    framework?: "nextjs" | "express" | "static" | "unknown";
+}
+export interface CheckpointRegisterResult {
+    registrationId: string;
+    claimToken: string;
+    claimUrl: string;
+    /**
+     * Short human-checkable code (`XXX-XXX`) derived from the registration
+     * id. The claim URL is first-claimer-wins with nothing binding it to
+     * the person who ran `checkpoint init`: if it leaks pre-claim (echoed
+     * into CI logs, shoulder-surfed), whoever opens it first claims it into
+     * THEIR org, and the real caller's CLI would otherwise proceed to
+     * install telemetry into the attacker's project. The claim page shows
+     * the same code so the human can cross-check terminal against browser
+     * before trusting a "claimed" status.
+     */
+    confirmationCode: string;
+    expiresAt: string;
+}
+export type CheckpointClaimStatus = "pending" | "claimed" | "expired";
+export interface CheckpointExchangeResult {
+    projectId: string;
+    friendlyId: string | null;
+    organizationId: string;
+    apiKey: string;
+    dashboardUrl: string;
+}
+/** True for an http(s) URL only -- never file:, vscode:, or any other scheme an OS handler might act on unexpectedly. */
+export declare function isHttpUrl(value: string): boolean;
+export declare const CONFIRMATION_CODE_RE: RegExp;
+export declare const API_KEY_RE: RegExp;
+export declare const PROJECT_ID_RE: RegExp;
+/**
+ * True only for an http(s) URL whose origin matches the configured
+ * Checkpoint origin. A same-shape check gated ONLY the open() call in
+ * checkpoint-init.ts (Bugbot, PR #658): announceClaim, the marker, and
+ * the --json payload still trusted and displayed any http(s) URL, so a
+ * compromised or misconfigured register response could still get a
+ * cross-origin, token-bearing link printed and persisted even though it
+ * was already judged unsafe to open. Validating at the source means
+ * every consumer of a parsed CheckpointRegisterResult gets the guarantee
+ * for free.
+ */
+export declare function isTrustedClaimUrl(value: string): boolean;
+/**
+ * `POST /api/cli/register`: mints a 24h claim token for this repo. The
+ * plaintext token is returned here and persisted (alongside
+ * `registrationId`) to `.checkpoint/registration.json` (0600, gitignored)
+ * by checkpoint-init.ts: a resumed run needs the token itself, not just
+ * the id, since the token IS the exchange credential.
+ */
+export declare function registerCheckpointProject(hints: CheckpointRegisterHints, signal?: AbortSignal): Promise<CheckpointRegisterResult>;
+/** `GET /api/cli/registrations/:id/status`: the poll target while waiting for the browser claim. */
+export declare function fetchCheckpointClaimStatus(registrationId: string, signal?: AbortSignal): Promise<CheckpointClaimStatus>;
+/** `POST /api/cli/exchange`: trades a claimed token for a project API key exactly once. */
+export declare function exchangeCheckpointClaim(claimToken: string, signal?: AbortSignal): Promise<CheckpointExchangeResult>;
+//# sourceMappingURL=checkpoint-api.d.ts.map

package/dist/utils/checkpoint-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-api.d.ts","sourceRoot":"","sources":["../../src/utils/checkpoint-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkBH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED,mHAAmH;AACnH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAiBpD;AAOD,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;CACzD;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAyBD,yHAAyH;AACzH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhD;AAUD,eAAO,MAAM,oBAAoB,QAA8B,CAAC;AAGhE,eAAO,MAAM,UAAU,QAA8B,CAAC;AACtD,eAAO,MAAM,aAAa,QAAsB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOxD;AAoDD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,uBAAuB,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAUnC;AAED,oGAAoG;AACpG,wBAAsB,0BAA0B,CAC9C,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAUhC;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAUnC"}

package/dist/utils/checkpoint-api.js

@@ -0,0 +1,196 @@
+/**
+ * HTTP client for the `kya-os checkpoint init` claim-token flow (KYA-1037).
+ *
+ * Talks to the three public Checkpoint dashboard endpoints added for this
+ * flow: register a claim token, poll its status, and exchange a claimed
+ * token for a project API key. Base URL is `CHECKPOINT_API_URL` when set,
+ * else the production dashboard origin, mirroring the `KTA_API_URL` /
+ * `KTA_BASE_URL` override pattern already used by `register.ts`/`claim.ts`
+ * for the sibling knowthat.ai claim flow.
+ */
+const DEFAULT_CHECKPOINT_ORIGIN = "https://kya.vouched.id";
+function checkpointApiUrl(path) {
+    const base = process.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_ORIGIN;
+    const url = new URL(base);
+    // new URL(path, base) would silently drop any path prefix already on
+    // `base` (e.g. a preview deploy served at http://localhost:3000/preview-x)
+    // because an absolute path like "/api/cli/register" overrides the
+    // base's own path entirely. Join onto the base's pathname instead so a
+    // prefix survives.
+    const prefix = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    const suffix = path.startsWith("/") ? path : `/${path}`;
+    url.pathname = `${prefix}${suffix}`;
+    return url.toString();
+}
+/**
+ * Reconstructs the claim URL from a token alone, same shape the register
+ * endpoint itself builds (`/cli/claim?token=...` off the same base). Used
+ * only as a fallback for a marker written before this CLI persisted the
+ * server-issued `claimUrl` directly; a current run always reprints the
+ * value the server returned at register time.
+ */
+export function buildCheckpointClaimUrl(claimToken) {
+    const url = new URL(checkpointApiUrl("/cli/claim"));
+    url.searchParams.set("token", claimToken);
+    return url.toString();
+}
+/** The configured Checkpoint origin (protocol + host), to host-match a server-returned URL before acting on it. */
+export function checkpointOrigin() {
+    const base = process.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_ORIGIN;
+    return new URL(base).origin;
+}
+/**
+ * True when CHECKPOINT_API_URL resolves to plain http on a non-localhost
+ * host: the claim token, and later the minted API key, cross that
+ * connection in the clear.
+ */
+export function isInsecureCheckpointOrigin() {
+    const base = process.env.CHECKPOINT_API_URL || DEFAULT_CHECKPOINT_ORIGIN;
+    try {
+        const url = new URL(base);
+        if (url.protocol !== "http:")
+            return false;
+        // WHATWG URL keeps the brackets on an IPv6 literal ("[::1]", not
+        // "::1"), so the un-bracketed form here was dead code and IPv6
+        // loopback (http://[::1]:PORT, real for local dev) incorrectly
+        // tripped the insecure-origin warning (bestbrian, PR #658 follow-up).
+        return (url.hostname !== "localhost" &&
+            url.hostname !== "127.0.0.1" &&
+            url.hostname !== "[::1]");
+    }
+    catch {
+        return false;
+    }
+}
+async function parseEnvelope(res) {
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || !body?.success || !body.data) {
+        const message = body?.error?.message || `Request failed with status ${res.status}`;
+        const error = new Error(message);
+        error.code = body?.error?.code;
+        throw error;
+    }
+    return body.data;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** True for an http(s) URL only -- never file:, vscode:, or any other scheme an OS handler might act on unexpectedly. */
+export function isHttpUrl(value) {
+    try {
+        const protocol = new URL(value).protocol;
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+// Exported so checkpoint-init.ts's isValidMarker can apply the SAME
+// shape checks to a marker read off disk, not just a fresh API response
+// (bestbrian, PR #658 follow-up review): a marker's apiKey/projectId/
+// claimUrl otherwise reached writeCheckpointEnv/the Beacon snippet/
+// announceClaim unchecked on the resume-after-exchange path, a gap a
+// hostile committed `.checkpoint/` directory could exploit even though
+// nothing here opens a new trust boundary a malicious repo doesn't
+// already have some other way in.
+export const CONFIRMATION_CODE_RE = /^[0-9A-F]{3}-[0-9A-F]{3}$/;
+// The two live formats the server mints (credentials.mdx): sk_... for
+// current keys, as_... as a real legacy format some paths still generate.
+export const API_KEY_RE = /^(sk|as)_[A-Za-z0-9._-]+$/;
+export const PROJECT_ID_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * True only for an http(s) URL whose origin matches the configured
+ * Checkpoint origin. A same-shape check gated ONLY the open() call in
+ * checkpoint-init.ts (Bugbot, PR #658): announceClaim, the marker, and
+ * the --json payload still trusted and displayed any http(s) URL, so a
+ * compromised or misconfigured register response could still get a
+ * cross-origin, token-bearing link printed and persisted even though it
+ * was already judged unsafe to open. Validating at the source means
+ * every consumer of a parsed CheckpointRegisterResult gets the guarantee
+ * for free.
+ */
+export function isTrustedClaimUrl(value) {
+    if (!isHttpUrl(value))
+        return false;
+    try {
+        return new URL(value).origin === checkpointOrigin();
+    }
+    catch {
+        return false;
+    }
+}
+/** Validates only the fields checkpoint-init.ts actually reads, not the whole declared shape. */
+function assertRegisterResult(data) {
+    const d = data;
+    if (!d ||
+        !isNonEmptyString(d.registrationId) ||
+        !isNonEmptyString(d.claimToken) ||
+        !isNonEmptyString(d.claimUrl) ||
+        !isTrustedClaimUrl(d.claimUrl) ||
+        !isNonEmptyString(d.confirmationCode) ||
+        !CONFIRMATION_CODE_RE.test(d.confirmationCode)) {
+        throw new Error("Malformed response from Checkpoint (register)");
+    }
+}
+function assertStatusResult(data) {
+    const status = data?.status;
+    if (status !== "pending" && status !== "claimed" && status !== "expired") {
+        throw new Error("Malformed response from Checkpoint (status)");
+    }
+}
+function assertExchangeResult(data) {
+    const d = data;
+    if (!d ||
+        // projectId and apiKey are format-checked, not just non-empty: both
+        // land in a sink an unvalidated newline could corrupt -- projectId
+        // into the Beacon snippet's JS string literal, apiKey into a raw
+        // .env.local line (a value containing "\nINJECTED=evil" would write
+        // a rogue env var into the user's app).
+        !isNonEmptyString(d.projectId) ||
+        !PROJECT_ID_RE.test(d.projectId) ||
+        !isNonEmptyString(d.apiKey) ||
+        !API_KEY_RE.test(d.apiKey) ||
+        !isNonEmptyString(d.dashboardUrl) ||
+        !isHttpUrl(d.dashboardUrl) ||
+        !isNonEmptyString(d.organizationId)) {
+        throw new Error("Malformed response from Checkpoint (exchange)");
+    }
+}
+/**
+ * `POST /api/cli/register`: mints a 24h claim token for this repo. The
+ * plaintext token is returned here and persisted (alongside
+ * `registrationId`) to `.checkpoint/registration.json` (0600, gitignored)
+ * by checkpoint-init.ts: a resumed run needs the token itself, not just
+ * the id, since the token IS the exchange credential.
+ */
+export async function registerCheckpointProject(hints, signal) {
+    const res = await fetch(checkpointApiUrl("/api/cli/register"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(hints),
+        signal,
+    });
+    const data = await parseEnvelope(res);
+    assertRegisterResult(data);
+    return data;
+}
+/** `GET /api/cli/registrations/:id/status`: the poll target while waiting for the browser claim. */
+export async function fetchCheckpointClaimStatus(registrationId, signal) {
+    const res = await fetch(checkpointApiUrl(`/api/cli/registrations/${encodeURIComponent(registrationId)}/status`), { signal });
+    const data = await parseEnvelope(res);
+    assertStatusResult(data);
+    return data.status;
+}
+/** `POST /api/cli/exchange`: trades a claimed token for a project API key exactly once. */
+export async function exchangeCheckpointClaim(claimToken, signal) {
+    const res = await fetch(checkpointApiUrl("/api/cli/exchange"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ claimToken }),
+        signal,
+    });
+    const data = await parseEnvelope(res);
+    assertExchangeResult(data);
+    return data;
+}
+//# sourceMappingURL=checkpoint-api.js.map

package/dist/utils/checkpoint-api.js.map

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

package/dist/utils/checkpoint-env.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal, dedicated `.env.local` writer for `kya-os checkpoint init`'s two
+ * variables.
+ *
+ * `EnvManager` (env-manager.ts) is intentionally NOT reused here: its
+ * `EnvVariables` interface and every parsing/regex path inside it are
+ * hardcoded to the MCP-I identity variable set (`AGENT_DID`,
+ * `AGENT_KEY_ID`, `KYA_VOUCHED_API_KEY`, ...). Feeding it
+ * `CHECKPOINT_API_KEY`/`CHECKPOINT_PROJECT_ID` would silently fall
+ * through its "unrecognized variable" branches and duplicate the lines on
+ * every re-run instead of updating them in place. This mirrors
+ * EnvManager's SAFE behaviors (prefer updating existing lines, append a
+ * clearly-labeled new section otherwise, never touch unrelated lines)
+ * scoped to just the two keys this command owns.
+ */
+export interface CheckpointEnvVars {
+    CHECKPOINT_API_KEY: string;
+    CHECKPOINT_PROJECT_ID: string;
+}
+export declare function writeCheckpointEnv(projectRoot: string, vars: CheckpointEnvVars): {
+    file: string;
+};
+//# sourceMappingURL=checkpoint-env.d.ts.map

package/dist/utils/checkpoint-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-env.d.ts","sourceRoot":"","sources":["../../src/utils/checkpoint-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAOD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,iBAAiB,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAyClB"}

package/dist/utils/checkpoint-env.js

@@ -0,0 +1,59 @@
+/**
+ * Minimal, dedicated `.env.local` writer for `kya-os checkpoint init`'s two
+ * variables.
+ *
+ * `EnvManager` (env-manager.ts) is intentionally NOT reused here: its
+ * `EnvVariables` interface and every parsing/regex path inside it are
+ * hardcoded to the MCP-I identity variable set (`AGENT_DID`,
+ * `AGENT_KEY_ID`, `KYA_VOUCHED_API_KEY`, ...). Feeding it
+ * `CHECKPOINT_API_KEY`/`CHECKPOINT_PROJECT_ID` would silently fall
+ * through its "unrecognized variable" branches and duplicate the lines on
+ * every re-run instead of updating them in place. This mirrors
+ * EnvManager's SAFE behaviors (prefer updating existing lines, append a
+ * clearly-labeled new section otherwise, never touch unrelated lines)
+ * scoped to just the two keys this command owns.
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+const ENV_KEYS = [
+    "CHECKPOINT_API_KEY",
+    "CHECKPOINT_PROJECT_ID",
+];
+export function writeCheckpointEnv(projectRoot, vars) {
+    const filePath = join(projectRoot, ".env.local");
+    const existing = existsSync(filePath) ? readFileSync(filePath, "utf-8") : "";
+    const lines = existing.length > 0 ? existing.split("\n") : [];
+    const seen = new Set();
+    const updatedLines = lines.map((line) => {
+        // Optional leading `export ` so a shell-sourced .env.local
+        // (`export CHECKPOINT_API_KEY=...`) gets updated in place too, rather
+        // than falling through to the "missing" branch and appending a
+        // duplicate line alongside it. The prefix (captured separately) is
+        // preserved on update, not silently dropped, so an exported var
+        // doesn't quietly become unexported.
+        const match = line.match(/^(export\s+)?([A-Z_][A-Z0-9_]*)\s*=/);
+        const exportPrefix = match?.[1] ?? "";
+        const key = match?.[2];
+        if (key && ENV_KEYS.includes(key)) {
+            seen.add(key);
+            return `${exportPrefix}${key}=${vars[key]}`;
+        }
+        return line;
+    });
+    const missing = ENV_KEYS.filter((key) => !seen.has(key));
+    if (missing.length > 0) {
+        if (updatedLines.length > 0 &&
+            updatedLines[updatedLines.length - 1] !== "") {
+            updatedLines.push("");
+        }
+        updatedLines.push("# Added by `kya-os checkpoint init`");
+        for (const key of missing) {
+            updatedLines.push(`${key}=${vars[key]}`);
+        }
+    }
+    // Exactly one trailing newline, regardless of what was there before.
+    const content = `${updatedLines.join("\n").replace(/\n+$/, "")}\n`;
+    writeFileSync(filePath, content, "utf-8");
+    return { file: ".env.local" };
+}
+//# sourceMappingURL=checkpoint-env.js.map

package/dist/utils/checkpoint-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-env.js","sourceRoot":"","sources":["../../src/utils/checkpoint-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,MAAM,QAAQ,GAAgC;IAC5C,oBAAoB;IACpB,uBAAuB;CACxB,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,IAAuB;IAEvB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,2DAA2D;QAC3D,sEAAsE;QACtE,+DAA+D;QAC/D,mEAAmE;QACnE,gEAAgE;QAChE,qCAAqC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAChE,MAAM,YAAY,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAwC,CAAC;QAC9D,IAAI,GAAG,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,GAAG,YAAY,GAAG,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,IACE,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,EAC5C,CAAC;YACD,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,CAAC;QACD,YAAY,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,MAAM,OAAO,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC;IACnE,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AAChC,CAAC"}

package/dist/utils/checkpoint-scaffold.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Detect-layer scaffolding for `kya-os checkpoint init` (KYA-1037).
+ *
+ * Maps the repo's detected platform onto one of the three Detect layers
+ * Checkpoint ships (Next.js middleware, Express snippet, the keyless
+ * Beacon), and, for Next.js, installs the SDK and writes middleware.ts
+ * directly (no shelling out to another package's setup script, see the
+ * comment on scaffoldNextjs for why). Every install/write step is behind
+ * an injectable ScaffoldRunner, so tests never spawn a real process or
+ * touch the real filesystem.
+ */
+import { type PlatformInfo } from "./platform-detector.js";
+export type CheckpointFramework = "nextjs" | "express" | "static" | "unknown";
+/**
+ * Maps `detectPlatform()`'s general-purpose platform/framework detection
+ * onto the three layers Checkpoint's `init` can scaffold. A repo with no
+ * `package.json` at all (a plain HTML/CSS/JS site) maps to `static`; one
+ * with a `package.json` but no recognized framework maps to `unknown`,
+ * both get the same keyless Beacon snippet, but the distinction is kept
+ * server-side as a hint for future support triage.
+ *
+ * Checks package.json's own `next` dependency directly, not just
+ * platformInfo's derived platform/framework fields: detectPlatform()
+ * unconditionally overwrites both to 'cloudflare'/'cloudflare-workers'
+ * whenever wrangler.toml/json exists, even for a Next.js repo deployed
+ * there, silently losing the nextjs detection underneath it.
+ */
+export declare function detectCheckpointFramework(projectRoot?: string, platformInfo?: PlatformInfo): CheckpointFramework;
+export declare function checkpointFrameworkLabel(framework: CheckpointFramework): string;
+/** Best-effort repo name: git remote slug, else the directory name. */
+export declare function detectRepoName(projectRoot?: string): string | undefined;
+/** Best-effort domain hint from `package.json`'s `homepage` field. */
+export declare function detectDomainHint(projectRoot?: string): string | undefined;
+export interface ScaffoldRunner {
+    /** Runs `command` with `args` in `cwd`; returns the exit status (0 = success). Never throws. */
+    run(command: string, args: string[], cwd: string): {
+        status: number;
+    };
+    /** Writes `content` to `path`. Throws on failure, so the caller can decide how to degrade. */
+    writeFile(path: string, content: string): void;
+    /** True if `path` exists. */
+    fileExists(path: string): boolean;
+}
+/** The real runner: shells out via execFileSync (swallowing spawn errors into a non-zero status) and touches the real filesystem. */
+export declare const defaultScaffoldRunner: ScaffoldRunner;
+export declare const NEXTJS_MANUAL_SNIPPET = "import { createMiddleware } from '@kya-os/checkpoint-nextjs';\n\nexport default createMiddleware({\n  apiKey: process.env.CHECKPOINT_API_KEY!,\n  projectId: process.env.CHECKPOINT_PROJECT_ID!,\n  // The SDK default is 'enforce', which is inert without a deployed\n  // policy, spelled out explicitly so flipping it later is a one-word diff.\n  enforcementMode: 'observe',\n});\n\nexport const config = { matcher: '/((?!_next/static|_next/image|favicon.ico).*)' };\n";
+export declare const EXPRESS_SNIPPET = "import { withCheckpoint } from '@kya-os/checkpoint-express';\n\napp.use(withCheckpoint({\n  apiKey: process.env.CHECKPOINT_API_KEY!,\n  projectId: process.env.CHECKPOINT_PROJECT_ID!,\n}));\n";
+export declare function beaconSnippet(projectId: string): string;
+export interface ScaffoldResult {
+    framework: CheckpointFramework;
+    /** True once the SDK package install succeeded (Next.js/Express only). */
+    installed: boolean;
+    /** True once the framework's own setup step (writing middleware.ts, printing the snippet) actually ran. */
+    setupRan: boolean;
+    /** Human-readable next step: either a success line or the manual wiring snippet + docs link. */
+    message: string;
+}
+export declare function scaffoldNextjs(projectRoot: string, packageManager: PlatformInfo["packageManager"], runner?: ScaffoldRunner): ScaffoldResult;
+export declare function scaffoldExpress(projectRoot: string, packageManager: PlatformInfo["packageManager"], runner?: ScaffoldRunner): ScaffoldResult;
+export declare function scaffoldBeacon(projectId: string, framework: CheckpointFramework): ScaffoldResult;
+//# sourceMappingURL=checkpoint-scaffold.d.ts.map

package/dist/utils/checkpoint-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-scaffold.d.ts","sourceRoot":"","sources":["../../src/utils/checkpoint-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAiB9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,GAAE,MAAsB,EACnC,YAAY,GAAE,YAA0C,GACvD,mBAAmB,CAarB;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAYR;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,WAAW,GAAE,MAAsB,GAClC,MAAM,GAAG,SAAS,CAkBpB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,WAAW,GAAE,MAAsB,GAClC,MAAM,GAAG,SAAS,CAkBpB;AAED,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,8FAA8F;IAC9F,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,6BAA6B;IAC7B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,qIAAqI;AACrI,eAAO,MAAM,qBAAqB,EAAE,cAwBnC,CAAC;AAiBF,eAAO,MAAM,qBAAqB,sdAWjC,CAAC;AAEF,eAAO,MAAM,eAAe,mMAM3B,CAAC;AAEF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,QAAQ,EAAE,OAAO,CAAC;IAClB,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;CACjB;AA+BD,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,YAAY,CAAC,gBAAgB,CAAC,EAC9C,MAAM,GAAE,cAAsC,GAC7C,cAAc,CAiDhB;AAED,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,YAAY,CAAC,gBAAgB,CAAC,EAC9C,MAAM,GAAE,cAAsC,GAC7C,cAAc,CAgBhB;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,mBAAmB,GAC7B,cAAc,CAOhB"}