carveout 0.1.1 → 0.1.2

package/dist/src/account.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `carveout login`, `whoami` and `logout` against the hosted platform
+ * (`platform.ts`). Each takes its argv and the outside world as `deps`, so
+ * test/platform.test.ts drives them against a fake platform with no real
+ * waiting; `cli.ts` runs them before it reads any slice option.
+ *
+ * login is RFC 8628's device flow on the platform's Better Auth:
+ *   POST /api/auth/device/code  {client_id}                          → device_code, user_code, verification_uri(_complete), expires_in, interval
+ *   POST /api/auth/device/token {grant_type, device_code, client_id} → access_token (a session that may only mint this client's token)
+ *   GET  /api/v1/me, GET /api/v1/me/orgs                               (with that session)
+ *   POST /api/v1/orgs/:orgId/tokens/cli {client, label}               → { token, secret }: a 90-day lnx_ token; the session ends
+ * The token is saved, never printed.
+ */
+export interface AccountDeps {
+    readonly env: NodeJS.ProcessEnv;
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+    readonly isTTY: boolean;
+    readonly ask: (question: string) => Promise<string>;
+    readonly sleep: (ms: number) => Promise<unknown>;
+    readonly now: () => number;
+    readonly fetchImpl: typeof fetch;
+    readonly openUrl: (url: string) => void;
+    readonly hostname: () => string;
+}
+export interface ClientId {
+    readonly client: string;
+    readonly version: string;
+}
+export type AccountCommand = "login" | "whoami" | "logout";
+/** The process's own world; tests pass their own. */
+export declare function defaultDeps(): AccountDeps;
+/** Runs one of the three, printing a PlatformError as one line on stderr. Answers the exit code. */
+export declare function runAccount(command: AccountCommand, argv: readonly string[], id: ClientId, deps?: AccountDeps): Promise<number>;
+export declare function login(argv: readonly string[], id: ClientId, deps: AccountDeps): Promise<number>;
+export declare function whoami(argv: readonly string[], { client, version }: ClientId, deps: AccountDeps): Promise<number>;
+export declare function logout(argv: readonly string[], { client }: ClientId, deps: AccountDeps): Promise<number>;

package/dist/src/account.js

@@ -0,0 +1,275 @@
+/**
+ * `carveout login`, `whoami` and `logout` against the hosted platform
+ * (`platform.ts`). Each takes its argv and the outside world as `deps`, so
+ * test/platform.test.ts drives them against a fake platform with no real
+ * waiting; `cli.ts` runs them before it reads any slice option.
+ *
+ * login is RFC 8628's device flow on the platform's Better Auth:
+ *   POST /api/auth/device/code  {client_id}                          → device_code, user_code, verification_uri(_complete), expires_in, interval
+ *   POST /api/auth/device/token {grant_type, device_code, client_id} → access_token (a session that may only mint this client's token)
+ *   GET  /api/v1/me, GET /api/v1/me/orgs                               (with that session)
+ *   POST /api/v1/orgs/:orgId/tokens/cli {client, label}               → { token, secret }: a 90-day lnx_ token; the session ends
+ * The token is saved, never printed.
+ */
+import { spawn } from "node:child_process";
+import { hostname as osHostname } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { credentialFor, credentialsPath, platformUrl, PlatformError, request, saveCredential } from "./platform.js";
+const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const ADMIN_ROLES = new Set(["owner", "admin"]);
+/** The process's own world; tests pass their own. */
+export function defaultDeps() {
+    return {
+        env: process.env,
+        out: (text) => process.stdout.write(text),
+        err: (text) => process.stderr.write(text),
+        isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        ask: async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        fetchImpl: fetch,
+        openUrl,
+        hostname: osHostname,
+    };
+}
+/** The OS's browser opener, detached; a failure is only a missed convenience. */
+function openUrl(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", '""', url]]
+            : ["xdg-open", [url]];
+    try {
+        spawn(command, args, { stdio: "ignore", detached: true })
+            .on("error", () => { })
+            .unref();
+    }
+    catch {
+        // The URL is printed either way.
+    }
+}
+/** Whether a held role (Better Auth joins several with commas) may mint a token. */
+const isAdmin = (role) => String(role)
+    .split(",")
+    .some((one) => ADMIN_ROLES.has(one.trim()));
+const describe = (org) => `${org.slug} (${org.name}, ${org.role}) ${org.id}`;
+function options(argv, spec, usage) {
+    try {
+        return parseArgs({
+            args: [...argv],
+            options: { ...spec, help: { type: "boolean", short: "h" } },
+            allowPositionals: false,
+        }).values;
+    }
+    catch (error) {
+        throw new PlatformError(`${error.message}\n${usage}`);
+    }
+}
+const text = (value) => (typeof value === "string" ? value : undefined);
+/** Runs one of the three, printing a PlatformError as one line on stderr. Answers the exit code. */
+export async function runAccount(command, argv, id, deps = defaultDeps()) {
+    try {
+        return await { login, whoami, logout }[command](argv, id, deps);
+    }
+    catch (error) {
+        if (!(error instanceof PlatformError))
+            throw error;
+        deps.err(`${id.client} ${command}: ${error.message}\n`);
+        return 1;
+    }
+}
+/** Picks the workspace to mint in: --org, the only one an owner or admin holds, or a choice on a TTY. */
+async function chooseOrg(orgs, wanted, client, deps) {
+    const eligible = orgs.filter((org) => isAdmin(org.role));
+    const listing = (list) => list.map((org) => `  ${describe(org)}`).join("\n");
+    const matches = (org, key) => org.id === key || org.slug.toLowerCase() === key.replace(/^@/, "").toLowerCase();
+    if (wanted !== undefined) {
+        const found = orgs.find((org) => matches(org, wanted));
+        if (found === undefined)
+            throw new PlatformError(`No workspace ${wanted} for this account. It has:\n${listing(orgs)}`);
+        if (!isAdmin(found.role)) {
+            throw new PlatformError(`You are ${found.role} in ${found.slug}; only its owners and admins can give ${client} a token.`);
+        }
+        return found;
+    }
+    const [only] = eligible;
+    if (eligible.length === 1 && only !== undefined)
+        return only;
+    if (eligible.length === 0) {
+        throw new PlatformError(orgs.length === 0
+            ? "This account has no workspace yet. Create one in the platform's web app, then run login again."
+            : `You are not an owner or admin of any workspace, and only they can give ${client} a token. This account has:\n${listing(orgs)}`);
+    }
+    if (!deps.isTTY) {
+        throw new PlatformError(`This account can sign in to ${eligible.length} workspaces; name one with --org <handle|id>:\n${listing(eligible)}`);
+    }
+    deps.out(`\nWorkspaces you can sign ${client} in to:\n${eligible.map((org, i) => `  ${i + 1}. ${describe(org)}`).join("\n")}\n`);
+    for (let tries = 0; tries < 3; tries += 1) {
+        const answer = (await deps.ask(`Workspace [1-${eligible.length}]: `)).trim();
+        const index = Number(answer);
+        const picked = Number.isInteger(index) && index >= 1 ? eligible[index - 1] : eligible.find((org) => matches(org, answer));
+        if (picked !== undefined)
+            return picked;
+    }
+    throw new PlatformError("No workspace chosen.");
+}
+/** Polls the token endpoint at the server's interval, five seconds slower after each `slow_down`, until approval, denial or expiry. */
+async function pollForSession(base, code, { client, version }, deps) {
+    let interval = Math.max(1, Number(code.interval) || 5) * 1000;
+    const deadline = deps.now() + Math.max(1, Number(code.expires_in) || 900) * 1000;
+    for (;;) {
+        await deps.sleep(interval);
+        if (deps.now() >= deadline)
+            throw new PlatformError("The code expired before it was approved. Run login again.");
+        try {
+            const granted = await request({
+                base,
+                method: "POST",
+                path: "/api/auth/device/token",
+                body: { grant_type: GRANT, device_code: code.device_code, client_id: client },
+                client,
+                version,
+                fetchImpl: deps.fetchImpl,
+            });
+            if (typeof granted.access_token !== "string")
+                throw new PlatformError("The platform approved the sign-in but sent no session.");
+            return granted.access_token;
+        }
+        catch (error) {
+            if (!(error instanceof PlatformError))
+                throw error;
+            if (error.code === "authorization_pending")
+                continue;
+            if (error.code === "slow_down") {
+                interval += 5000;
+                continue;
+            }
+            if (error.code === "expired_token")
+                throw new PlatformError("The code expired before it was approved. Run login again.");
+            if (error.code === "access_denied")
+                throw new PlatformError("The sign-in was denied in the browser. Nothing was saved.");
+            if (error.code === "invalid_grant")
+                throw new PlatformError("The code is no longer valid (already used, or unknown). Run login again.");
+            throw error;
+        }
+    }
+}
+export async function login(argv, id, deps) {
+    const { client, version } = id;
+    const usage = `usage: ${client} login [--platform <url>] [--org <handle|id>] [--open]`;
+    const values = options(argv, { platform: { type: "string" }, org: { type: "string" }, open: { type: "boolean" } }, usage);
+    if (values["help"] === true) {
+        deps.out(`${usage}\n\nSigns ${client} in to the Lunox platform (default ${platformUrl(undefined, {})}; LUNOX_PLATFORM_URL) with a code\n` +
+            `you approve in the browser, and saves a workspace token in ${credentialsPath(deps.env)} (LUNOX_CREDENTIALS).\n` +
+            `--org picks the workspace; --open opens the approval page.\n`);
+        return 0;
+    }
+    const base = platformUrl(text(values["platform"]), deps.env);
+    const call = (more) => request({ base, client, version, fetchImpl: deps.fetchImpl, ...more });
+    const code = await call({ method: "POST", path: "/api/auth/device/code", body: { client_id: client } });
+    if (typeof code.device_code !== "string" || typeof code.user_code !== "string") {
+        throw new PlatformError(`${base} answered the sign-in request without a code.`);
+    }
+    const page = code.verification_uri_complete ?? code.verification_uri ?? `${base}/device`;
+    const minutes = Math.round((Number(code.expires_in) || 900) / 60);
+    deps.out(`To sign ${client} in to ${base}, open this page and approve the code:\n\n  ${page}\n\n` +
+        `  Code: ${code.user_code} (expires in ${minutes} minute${minutes === 1 ? "" : "s"})\n\n`);
+    if (values["open"] === true)
+        deps.openUrl(page);
+    deps.out("Waiting for approval...\n");
+    const session = await pollForSession(base, code, id, deps);
+    const asSession = (more) => call({ token: session, session: true, ...more });
+    let minted;
+    let me;
+    let org;
+    try {
+        me = (await asSession({ path: "/api/v1/me" })).user;
+        const orgs = (await asSession({ path: "/api/v1/me/orgs" })).organizations ?? [];
+        org = await chooseOrg(orgs, text(values["org"]), client, deps);
+        const label = String(deps.hostname() ?? "")
+            .trim()
+            .slice(0, 60);
+        minted = await asSession({
+            method: "POST",
+            path: `/api/v1/orgs/${encodeURIComponent(org.id)}/tokens/cli`,
+            body: label === "" ? { client } : { client, label },
+        });
+    }
+    catch (error) {
+        // Minting ends the session; a sign-in that stopped short ends it here, best effort.
+        await asSession({ method: "POST", path: "/api/auth/sign-out", body: {} }).catch(() => { });
+        throw error;
+    }
+    if (typeof minted.secret !== "string" || !minted.secret.startsWith("lnx_")) {
+        throw new PlatformError(`${base} answered without a workspace token.`);
+    }
+    const path = credentialsPath(deps.env);
+    const expiresAt = minted.token?.expiresAt ?? null;
+    saveCredential(path, base, client, {
+        token: minted.secret,
+        organizationId: org.id,
+        organizationHandle: org.slug,
+        client,
+        createdAt: minted.token?.createdAt ?? new Date(deps.now()).toISOString(),
+        expiresAt,
+    });
+    const who = me ? `${me.name} <${me.email}>` : "you";
+    const expiry = expiresAt ? `; it expires ${expiresAt.slice(0, 10)}` : "";
+    deps.out(`Signed in as ${who}, workspace ${org.name} (@${org.slug}) on ${base}.\nToken saved to ${path}${expiry}.\n`);
+    return 0;
+}
+export async function whoami(argv, { client, version }, deps) {
+    const usage = `usage: ${client} whoami [--platform <url>]`;
+    const values = options(argv, { platform: { type: "string" } }, usage);
+    if (values["help"] === true) {
+        deps.out(`${usage}\n\nThe account, workspace and token expiry ${client} is signed in with.\n`);
+        return 0;
+    }
+    const base = platformUrl(text(values["platform"]), deps.env);
+    const saved = credentialFor(credentialsPath(deps.env), base, client);
+    if (saved === undefined)
+        throw new PlatformError(`Not signed in to ${base}. Run \`${client} login\`.`);
+    const call = (path) => request({ base, token: saved.token, path, client, version, fetchImpl: deps.fetchImpl });
+    const { user } = await call("/api/v1/me");
+    const { organization, role } = await call(`/api/v1/orgs/${encodeURIComponent(saved.organizationId)}`);
+    const expires = saved.expiresAt ? `expires ${saved.expiresAt.slice(0, 10)}` : "does not expire";
+    deps.out([
+        `user       ${user.name} <${user.email}>${user.username ? ` (@${user.username})` : ""}`,
+        `workspace  ${organization.name} (@${organization.slug}), ${role}`,
+        `platform   ${base}`,
+        `token      ${client}, ${expires}`,
+        "",
+    ].join("\n"));
+    return 0;
+}
+export async function logout(argv, { client }, deps) {
+    const usage = `usage: ${client} logout [--platform <url>]`;
+    const values = options(argv, { platform: { type: "string" } }, usage);
+    if (values["help"] === true) {
+        deps.out(`${usage}\n\nDeletes ${client}'s saved token for the platform.\n`);
+        return 0;
+    }
+    const base = platformUrl(text(values["platform"]), deps.env);
+    const path = credentialsPath(deps.env);
+    const saved = credentialFor(path, base, client);
+    if (saved === undefined) {
+        deps.out(`Not signed in to ${base}; nothing to do.\n`);
+        return 0;
+    }
+    saveCredential(path, base, client, undefined);
+    // The platform lets no API token revoke itself (token routes take a person's session), so this is local.
+    const until = saved.expiresAt ? `until ${saved.expiresAt.slice(0, 10)}` : "until it is revoked";
+    deps.out(`Signed out of ${base}: the token is deleted from ${path}.\n` +
+        `The platform has no route for a token to revoke itself, so it stays valid ${until} unless an owner or\n` +
+        `admin of @${saved.organizationHandle} revokes it in the platform's web app (the workspace's API tokens).\n`);
+    return 0;
+}

package/dist/src/api.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The library entry, `carveout/api`: plan, cut and patch for a platform
+ * that keeps the receipt itself, on the code paths the CLI runs
+ * (`planSlice`, `cutSlice`, `patchProject` in `carve.ts`).
+ *
+ * What it holds to: it never starts Docker or any container, never runs
+ * the folder's code (no install, build or test of it; `check` and `merge`
+ * are not here), and never reads or writes `CARVEOUT_HOME` (`~/.carveout`):
+ * the receipt goes out of `cut` and into `patch` as data. What it may run
+ * is Git, read-only, on the repository (its commit and files) and, for a
+ * patch with edits, in a scratch repository of its own; and, only for a
+ * `cut` that is not `offline`, npm with scripts off to fetch package types
+ * (into `typesCache`, else a temporary folder) and to resolve the folder's
+ * lockfile. `test/api.test.ts` holds it to that with `child_process` made
+ * to throw.
+ *
+ * Also exported: the policy's text checks (`integrityOf`,
+ * `gainedIntegrity`, `weakenedTest`) and the slice and project modules
+ * `core.ts` gathers, forked from sandbox-factory's core.
+ */
+import { type CarveoutRecord, type Patch, type PlanSurface } from "./carve.js";
+import { type CutEdge, type SliceExposure, type SliceExternals, type SliceOrigin, type SliceTestLeft, type TestRunner } from "./core.js";
+import type { Readiness } from "./readiness.js";
+import type { Receipt } from "./receipt.js";
+export * from "./core.js";
+export { gainedIntegrity, integrityOf, weakenedTest, type Refusal } from "./policy.js";
+export type { CarveoutRecord, Patch, PlanSurface, Readiness, Receipt };
+/** The walk's bounds, as `carveout plan` and `cut` take them. */
+export interface WalkOptions {
+    /** The repository's checkout root. */
+    readonly root: string;
+    /** Files or folders, relative to the root. */
+    readonly entries: readonly string[];
+    /** Import depth from the entries (`--depth`, default 3). */
+    readonly depth?: number;
+    /** Most files the folder holds (`--max-files`, default 40). */
+    readonly maxFiles?: number;
+    /** Bring the tests outside the slice that import it (`--with-tests`). */
+    readonly withTests?: boolean;
+    /** Copy the pure code the slice runs rather than mock it (`--copy-pure`). */
+    readonly copyPure?: boolean;
+}
+/** What a cut of the entries would hold; nothing is written. */
+export interface PlanResult {
+    readonly root: string;
+    readonly entries: readonly string[];
+    /** Entries that name no script file of the repository. */
+    readonly unknownEntries: readonly string[];
+    readonly budget: {
+        readonly maxFiles: number;
+        readonly maxDepth: number;
+    };
+    /** The files the folder would copy, sorted, with why each is there and its depth. */
+    readonly included: readonly string[];
+    readonly originOf: Readonly<Record<string, SliceOrigin>>;
+    readonly depthOf: Readonly<Record<string, number>>;
+    /** Files the walk reached past the file budget: cut instead. */
+    readonly dropped: readonly string[];
+    /** Pure code copied rather than mocked (`copyPure`). */
+    readonly pure: readonly string[];
+    /** Cut modules (each a stub and a mock), those imported for types only, and every import that crosses out. */
+    readonly cuts: {
+        readonly modules: readonly string[];
+        readonly typeOnly: readonly string[];
+        readonly outbound: readonly CutEdge[];
+    };
+    /** The slice's modules code outside it imports: the names taken and the importers. */
+    readonly surface: readonly PlanSurface[];
+    /** Tests of the slice: carried, each with its runner; left in the repository, each with the reason. */
+    readonly tests: {
+        readonly verdict: string;
+        readonly carried: readonly {
+            readonly file: string;
+            readonly runner: TestRunner;
+        }[];
+        readonly helpers: readonly string[];
+        readonly left: readonly (SliceTestLeft & {
+            readonly why: string;
+        })[];
+    };
+    /** Bare packages the slice imports, and of those the repository's own workspaces. */
+    readonly packages: readonly string[];
+    readonly workspacePackages: readonly string[];
+    /** Services and environment the slice reads. */
+    readonly externals: SliceExternals;
+    /** What the folder would show of the repository, by origin. */
+    readonly exposure: SliceExposure;
+    /** What stops the cut, one line each, as `carveout plan` prints them. */
+    readonly blockers: readonly string[];
+}
+/** `carveout plan`: the files, cuts, public surface and tests of a cut, from the import graph. Writes nothing. */
+export declare function plan(options: WalkOptions): PlanResult;
+export interface CutOptions extends WalkOptions {
+    /** An empty or new folder, outside the repository. */
+    readonly out: string;
+    /**
+     * No network: no package types fetched and no lockfile resolved, so
+     * nothing but Git is run. Off: npm, scripts off, does both.
+     */
+    readonly offline?: boolean;
+    /**
+     * A folder for someone outside (`--public`): literals widened and the
+     * repository's names in pseudonyms under the receipt's table. Off here
+     * whatever `carveout.config.json` says, for a caller with its own names.
+     */
+    readonly public?: boolean;
+    /** Where fetched package types are kept between cuts; a temporary folder, removed after, by default. */
+    readonly typesCache?: string;
+    /** The cut's progress lines. */
+    readonly log?: (line: string) => void;
+}
+export interface CutOutput {
+    /** The folder, absolute. */
+    readonly out: string;
+    /** What the folder's `carveout.json` holds. */
+    readonly record: CarveoutRecord;
+    /** Whether it is written without blockers. */
+    readonly ready: boolean;
+    readonly blockers: CarveoutRecord["blockers"];
+    /** The maintainer's receipt, as data: keep it private, and give it to `patch`. Written nowhere. */
+    readonly receipt: Receipt;
+    /** What would make the folder's tests run on real code. */
+    readonly readiness: Readiness;
+}
+/**
+ * `carveout cut`: writes the folder and its `carveout.json` as the CLI
+ * does, and returns the receipt as data instead of writing it under
+ * `~/.carveout/receipts/`.
+ */
+export declare function cut(options: CutOptions): Promise<CutOutput>;
+export interface PatchInput {
+    /** The receipt `cut` returned for this folder. */
+    readonly receipt: Receipt;
+    /** The folder as it came back. */
+    readonly folder: string;
+    /** The repository's checkout; by default the one the receipt names. It must hold the cut's commit. */
+    readonly repo?: string;
+    /** Paths and globs the hand-off policy lets through (`--allow`). */
+    readonly allow?: readonly string[];
+}
+/**
+ * `carveout patch`: the folder's edits as a patch for the repository, its
+ * imports and names put back, with what the hand-off policy keeps out in
+ * `refused` (the CLI's exit 6) and what reaches past the slice in
+ * `boundary` (exit 5). Judged by the receipt given, never by the folder's
+ * own record; runs nothing from the folder.
+ */
+export declare function patch(input: PatchInput): Promise<Patch>;

package/dist/src/api.js

@@ -0,0 +1,120 @@
+/**
+ * The library entry, `carveout/api`: plan, cut and patch for a platform
+ * that keeps the receipt itself, on the code paths the CLI runs
+ * (`planSlice`, `cutSlice`, `patchProject` in `carve.ts`).
+ *
+ * What it holds to: it never starts Docker or any container, never runs
+ * the folder's code (no install, build or test of it; `check` and `merge`
+ * are not here), and never reads or writes `CARVEOUT_HOME` (`~/.carveout`):
+ * the receipt goes out of `cut` and into `patch` as data. What it may run
+ * is Git, read-only, on the repository (its commit and files) and, for a
+ * patch with edits, in a scratch repository of its own; and, only for a
+ * `cut` that is not `offline`, npm with scripts off to fetch package types
+ * (into `typesCache`, else a temporary folder) and to resolve the folder's
+ * lockfile. `test/api.test.ts` holds it to that with `child_process` made
+ * to throw.
+ *
+ * Also exported: the policy's text checks (`integrityOf`,
+ * `gainedIntegrity`, `weakenedTest`) and the slice and project modules
+ * `core.ts` gathers, forked from sandbox-factory's core.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cutSlice, patchProject, planBlockers, planSlice, } from "./carve.js";
+import { SLICE_BUDGET_DEFAULTS, TEST_LEFT_REASON, testsVerdict, } from "./core.js";
+export * from "./core.js";
+export { gainedIntegrity, integrityOf, weakenedTest } from "./policy.js";
+const budgetOf = (options) => ({
+    maxFiles: options.maxFiles ?? SLICE_BUDGET_DEFAULTS.maxFiles,
+    maxDepth: options.depth ?? SLICE_BUDGET_DEFAULTS.maxDepth,
+});
+/** The walk's options as `SliceRequest` fields; unset ones are left to the repository's `carveout.config.json`. */
+const requestOf = (options) => ({
+    repo: options.root,
+    entryPoints: options.entries,
+    budget: budgetOf(options),
+    ...(options.withTests === undefined ? {} : { tests: options.withTests }),
+    ...(options.copyPure === undefined ? {} : { copyPure: options.copyPure }),
+});
+/** `carveout plan`: the files, cuts, public surface and tests of a cut, from the import graph. Writes nothing. */
+export function plan(options) {
+    const planned = planSlice(requestOf(options));
+    const { walk } = planned;
+    return {
+        root: planned.repo,
+        entries: planned.entryPoints,
+        unknownEntries: walk.unknownEntryPoints,
+        budget: planned.budget,
+        included: walk.included,
+        originOf: walk.originOf,
+        depthOf: walk.depthOf,
+        dropped: walk.dropped,
+        pure: walk.pure,
+        cuts: { modules: planned.cutModules, typeOnly: planned.typeOnlyCuts, outbound: walk.cuts.outbound },
+        surface: planned.surface,
+        tests: {
+            verdict: testsVerdict(walk),
+            carried: walk.tests.flatMap((file) => {
+                const runner = planned.testRunners[file];
+                return runner === undefined ? [] : [{ file, runner }];
+            }),
+            helpers: walk.helpers,
+            left: walk.testsLeft.map((left) => ({ ...left, why: TEST_LEFT_REASON[left.reason] })),
+        },
+        packages: planned.packages,
+        workspacePackages: planned.workspacePackages,
+        externals: planned.externals,
+        exposure: planned.exposure,
+        blockers: planBlockers(planned),
+    };
+}
+/**
+ * `carveout cut`: writes the folder and its `carveout.json` as the CLI
+ * does, and returns the receipt as data instead of writing it under
+ * `~/.carveout/receipts/`.
+ */
+export async function cut(options) {
+    const offline = options.offline === true;
+    const types = offline || options.typesCache !== undefined ? null : mkdtempSync(join(tmpdir(), "carveout-types-"));
+    try {
+        const result = await cutSlice({
+            ...requestOf(options),
+            out: options.out,
+            offline,
+            public: options.public ?? false,
+            receiptInMemory: true,
+            ...(options.typesCache !== undefined ? { typesCache: options.typesCache } : types === null ? {} : { typesCache: types }),
+            ...(options.log === undefined ? {} : { log: options.log }),
+        });
+        const receipt = result.receiptData;
+        if (receipt === null)
+            throw new Error("The cut kept no receipt.");
+        return {
+            out: result.out,
+            record: receipt.folderRecord ?? receipt.record,
+            ready: result.record.ready,
+            blockers: result.record.blockers,
+            receipt,
+            readiness: result.readiness,
+        };
+    }
+    finally {
+        if (types !== null)
+            rmSync(types, { recursive: true, force: true });
+    }
+}
+/**
+ * `carveout patch`: the folder's edits as a patch for the repository, its
+ * imports and names put back, with what the hand-off policy keeps out in
+ * `refused` (the CLI's exit 6) and what reaches past the slice in
+ * `boundary` (exit 5). Judged by the receipt given, never by the folder's
+ * own record; runs nothing from the folder.
+ */
+export function patch(input) {
+    return patchProject(input.folder, {
+        receiptData: input.receipt,
+        ...(input.repo === undefined ? {} : { repo: input.repo }),
+        ...(input.allow === undefined ? {} : { allow: input.allow }),
+    });
+}