carveout 0.3.1 → 0.4.0

package/README.md

@@ -270,9 +270,17 @@ agent once per stop:
 | `carveout whoami`             | Print the account, workspace and token expiry signed in with                   |
 | `carveout logout`             | Delete the saved platform token                                                |
 
-Every option: [reference](docs/REFERENCE.md#commands). Only `login`, `whoami`
-and `logout` talk to the Lunox platform; every other command is local and needs
-no account.
+Every option: [reference](docs/REFERENCE.md#commands). Only `login`, `whoami`,
+`logout`, `handoff --platform` and `patch --from` talk to the Lunox platform;
+every other command is local and needs no account.
+
+For a repository you will not connect to the platform, `carveout handoff
+<entry>... --accept <test>... --platform --bounty <id>` uploads the ready
+folder, public and in pseudonyms, with your acceptance tests renamed into its
+names, as a version of that bounty; the receipt stays on your machine. The
+platform grades contractors' submissions against it, and `carveout patch
+--from <submission id>` brings a passing one back through the same local
+`patch`. Publishing the version is a person's act in the platform's web app.
 
 ## Limits
 

package/dist/src/carve.d.ts

@@ -15,7 +15,7 @@ import { type SandboxSpec } from "./sandbox.js";
 import { type Readiness } from "./readiness.js";
 import { type AliasRule, type FolderPseudonyms } from "./pseudonyms/index.js";
 import { type Receipt } from "./receipt.js";
-export declare const CARVEOUT_VERSION = "0.3.1";
+export declare const CARVEOUT_VERSION = "0.4.0";
 export declare const RECORD_PATH = "carveout.json";
 export declare const RECORD_SCHEMA_VERSION = 1;
 export declare const BOUNDARY_PATH = "BOUNDARY.md";

package/dist/src/carve.js

@@ -35,7 +35,7 @@ import { sandboxRun } from "./sandbox.js";
 import { configuredFolders, liveCandidates } from "./readiness.js";
 import { exactToFolder, fromFolder, specifierPackages, toFolder, keptNames, looseLeaks, maskKept, pseudonymize, vocabularyBlockers, vocabularyLeaks, workspaceNames, ownedNames, workspaceVocabulary, } from "./pseudonyms/index.js";
 import { RECEIPT_SCHEMA_VERSION, folderRecordFor, folderView, newCutId, receiptPathFor, trustedBaseline, trustedCut, trustedCutWith, writeReceipt, } from "./receipt.js";
-export const CARVEOUT_VERSION = "0.3.1";
+export const CARVEOUT_VERSION = "0.4.0";
 export const RECORD_PATH = "carveout.json";
 export const RECORD_SCHEMA_VERSION = 1;
 /** Blockers that stop a cut before it writes anything. */

package/dist/src/cli.js

@@ -20,18 +20,24 @@ import { statusProject } from "./status.js";
 import { hasAdvice, renderReadiness } from "./readiness.js";
 import { trustedCut, writeReceipt } from "./receipt.js";
 import { runAccount } from "./account.js";
+import { handoffPlatform, patchFrom } from "./hosted.js";
+import { PlatformError } from "./platform.js";
 const USAGE = `carveout ${CARVEOUT_VERSION}: carve a slice out of a TypeScript repository.
 
   carveout handoff <entry>... --out <dir> [--task <file|text>] [--depth N] [--max-files N]
                  [--private <path>]... [--name <word>]... [--copy <dir>]... [--live <pkg>]...
                  [--accept <test>...] [--no-whole-package] [--no-copy-pure] [--receipt <file>]
-                 [--max-exposure-lines N] [--max-exposure-percent P] [--json]
+                 [--max-exposure-lines N] [--max-exposure-percent P]
+                 [--platform [<url>] --bounty <id> [--title <text>]] [--json]
       The hand-off in one step: a cut with the tests that run the code, its
       whole package and the pure code it runs, for someone outside (public,
       in pseudonyms), and its check. Prints whether the folder is ready (its
       tests pass before any edit), what it shows, the receipt to keep, and
       what to send. --task writes TASK.md: the work, and when it is accepted.
-      Exits 0 only when the folder is ready to hand over.
+      Exits 0 only when the folder is ready to hand over. --platform (after
+      carveout login) uploads the ready folder and the --accept tests, in the
+      folder's names, as a draft version of the bounty --bounty names; the
+      receipt stays here. Publishing it is a person's act in the web app.
 
   carveout plan  <entry>... [--repo <dir>] [--max-files N] [--depth N]
                  [--with-tests] [--whole-package] [--follow-workspaces]
@@ -82,10 +88,15 @@ const USAGE = `carveout ${CARVEOUT_VERSION}: carve a slice out of a TypeScript r
 
   carveout patch <dir> [--repo <checkout>] [--allow <path>]... [--receipt <file>]
                  [--output <file>] [--json]
+  carveout patch --from <submission-id> [--platform [<url>]] [--repo <checkout>]
+                 [--allow <path>]... [--output <file>] [--json]
       The edits made in <dir> as a patch for the repository (git apply). Runs
       none of the folder's code. Keeps out, and names, new files outside the
       slice's packages, protected paths (CI, hooks, manifests, lockfiles,
       environment) and deleted tests; --allow <path|glob> lets one through.
+      --from takes a passing submission's files from the platform, on a folder
+      handoff --platform uploaded from here, and judges them the same way,
+      by the local receipt.
 
   carveout apply <dir> <patch-file> [--repo <checkout>] [--stubs] [--receipt <file>] [--json]
       Brings a patch for the repository at the cut's commit into <dir>, with its
@@ -144,7 +155,7 @@ const USAGE = `carveout ${CARVEOUT_VERSION}: carve a slice out of a TypeScript r
       workspace token in ~/.lunox/credentials (LUNOX_CREDENTIALS), shared with
       duediligence; whoami prints the account, workspace and token expiry;
       logout deletes the token here (the platform cannot revoke it from the
-      CLI). No other command talks to the platform.
+      CLI). Only handoff --platform and patch --from talk to it besides.
 
 An entry point is a file or a directory, relative to --repo (default: the
 current directory, which should be the repository's root). Defaults:
@@ -252,8 +263,10 @@ async function main(argv) {
         process.exitCode = await runAccount(commandName, rest, { client: "carveout", version: CARVEOUT_VERSION });
         return;
     }
+    // `--platform` with no URL: the default platform (LUNOX_PLATFORM_URL, else production).
+    const args = rest.map((arg, i) => arg === "--platform" && (rest[i + 1] === undefined || rest[i + 1]?.startsWith("-")) ? "--platform=" : arg);
     const { values, positionals } = parseArgs({
-        args: [...rest],
+        args,
         allowPositionals: true,
         // `--no-whole-package`, `--no-copy-pure`, `--no-public`: handoff's
         // defaults turned off by name.
@@ -301,6 +314,10 @@ async function main(argv) {
             "keep-names": { type: "boolean" },
             task: { type: "string" },
             entry: { type: "string", multiple: true },
+            platform: { type: "string" },
+            bounty: { type: "string" },
+            title: { type: "string" },
+            from: { type: "string" },
         },
     });
     // With negated flags read, `--no-receipt` comes back as `receipt: false`
@@ -383,6 +400,9 @@ async function main(argv) {
         ...(values.private === undefined ? {} : { private: values.private }),
         ...maxExposure,
     };
+    /** `--platform`'s URL; undefined for the default. */
+    const platformGiven = values.platform === undefined || values.platform === "" ? undefined : values.platform;
+    const hostedDeps = () => ({ env: process.env, fetchImpl: fetch, now: Date.now });
     switch (commandName) {
         case "where":
             process.stdout.write(`${carveoutHome()}\n`);
@@ -519,6 +539,15 @@ async function main(argv) {
                 fail("handoff needs at least one entry point.");
             if (values.out === undefined)
                 fail("handoff needs --out <dir>.");
+            const toPlatform = values.platform !== undefined;
+            if (toPlatform) {
+                if (values.bounty === undefined)
+                    fail("handoff --platform needs --bounty <id>: the bounty the folder is a version of.");
+                if (values["keep-names"] === true || values.public === false || values["no-receipt"] === true)
+                    fail("handoff --platform uploads a public folder in pseudonyms, with its receipt kept here: drop --keep-names, --no-public and --no-receipt.");
+                if ((values.accept ?? []).length === 0)
+                    fail("handoff --platform needs --accept <test>...: the platform grades a submission by the tests that fail before the work.");
+            }
             // The hand-off's own defaults, unless a flag or the owner's
             // configuration says otherwise: the tests that run the code, its
             // whole package, the pure code it runs, and a folder for someone
@@ -580,6 +609,38 @@ async function main(argv) {
             const record = result.record;
             // The step that failed, and what it printed last: what to fix first.
             const failedStep = steps.find((step) => !step.ok);
+            // To the platform: only a folder ready to hand over, public and in
+            // pseudonyms, whose acceptance tests fail before the work.
+            let uploaded = null;
+            let notUploaded = null;
+            if (toPlatform) {
+                if (!record.ready || (verdict.handoff !== "ready" && verdict.handoff !== "no-tests"))
+                    notUploaded = "the folder is not ready to hand over (above); fix it and hand off again.";
+                else if (vacuous !== false)
+                    notUploaded =
+                        vacuous === true
+                            ? "the acceptance tests already pass before the work, so they would accept anything."
+                            : "the acceptance tests did not run on the folder (above).";
+                else if (result.receipt === null || result.pseudonyms === null)
+                    notUploaded = "the folder is not in pseudonyms with a receipt kept here.";
+                else
+                    try {
+                        uploaded = await handoffPlatform({
+                            platform: platformGiven,
+                            bountyId: values.bounty ?? "",
+                            folder: result.out,
+                            receiptPath: result.receipt,
+                            accepted,
+                            title: values.title,
+                            deps: hostedDeps(),
+                        });
+                    }
+                    catch (error) {
+                        if (!(error instanceof PlatformError))
+                            throw error;
+                        notUploaded = error.message;
+                    }
+            }
             if (values.json === true)
                 print({
                     out: result.out,
@@ -595,6 +656,21 @@ async function main(argv) {
                     // The owner's acceptance tests on the folder as it goes out.
                     acceptance: vacuous === null ? null : vacuous ? "pass-before-the-work" : "fail-before-the-work",
                     steps,
+                    ...(toPlatform
+                        ? {
+                            platform: uploaded === null
+                                ? { uploaded: false, reason: notUploaded }
+                                : {
+                                    uploaded: true,
+                                    base: uploaded.base,
+                                    bountyId: uploaded.bountyId,
+                                    sandboxId: uploaded.sandboxId,
+                                    versionId: uploaded.versionId,
+                                    runId: uploaded.runId,
+                                    record: uploaded.recordPath,
+                                },
+                        }
+                        : {}),
                 });
             else {
                 const lines = [
@@ -642,15 +718,29 @@ async function main(argv) {
                     result.receipt === null
                         ? "No receipt: the folder that comes back will be judged by its own record (--no-receipt on patch)."
                         : `Receipt: ${result.receipt}\n  Keep it, and never send it: the folder that comes back is judged by it.`,
-                    `Send the folder without node_modules: (cd ${dirname(result.out)} && zip -qr ${basename(result.out)}.zip ${basename(result.out)} -x '*/node_modules/*')`,
-                    "When it comes back, from the repository's root: carveout patch <returned folder> --output change.patch; read all of it; then git apply --3way change.patch on a branch, and let CI decide.",
-                    "",
+                    ...(uploaded !== null
+                        ? [
+                            `Uploaded to ${uploaded.base}: version ${uploaded.versionId} of bounty ${uploaded.bountyId} (sandbox ${uploaded.sandboxId}, import run ${uploaded.runId}), ${uploaded.files} file(s) and ${accepted.length} acceptance test(s) in the folder's names. The receipt stayed here; the upload is recorded in ${uploaded.recordPath}.`,
+                            "  The platform runs the folder's baseline (each acceptance test must fail on it). Publishing the version is a person's act in the platform's web app.",
+                            "When a contributor's submission passes, from the repository's root: carveout patch --from <submission id> --output change.patch; read all of it; then git apply --3way change.patch on a branch, and let CI decide.",
+                            "",
+                        ]
+                        : [
+                            ...(notUploaded === null ? [] : [`Not uploaded to the platform: ${notUploaded}`, ""]),
+                            `Send the folder without node_modules: (cd ${dirname(result.out)} && zip -qr ${basename(result.out)}.zip ${basename(result.out)} -x '*/node_modules/*')`,
+                            "When it comes back, from the repository's root: carveout patch <returned folder> --output change.patch; read all of it; then git apply --3way change.patch on a branch, and let CI decide.",
+                            "",
+                        ]),
                 ];
                 process.stdout.write(lines.join("\n"));
             }
             // Acceptance tests that pass before the work would accept anything.
             if (!record.ready || verdict.handoff !== "ready" || vacuous === true)
                 process.exitCode = 2;
+            if (toPlatform && uploaded === null)
+                process.exitCode = 1;
+            else if (uploaded !== null)
+                process.exitCode = 0;
             return;
         }
         case "cut": {
@@ -965,14 +1055,39 @@ async function main(argv) {
         }
         case "patch": {
             const [dir] = positionals;
-            if (dir === undefined)
-                fail("patch needs the folder a cut wrote.");
-            const given = repoFor(dir);
-            const patch = await patchProject(dir, {
-                ...(given === undefined ? {} : { repo: given }),
-                ...(values.allow === undefined ? {} : { allow: values.allow }),
-                ...receiptOption,
-            });
+            let patch;
+            if (values.from !== undefined) {
+                if (dir !== undefined)
+                    fail("patch --from takes a submission id, not a folder.");
+                let from;
+                try {
+                    from = await patchFrom({
+                        platform: platformGiven,
+                        submissionId: values.from,
+                        repo: values.repo,
+                        allow: values.allow,
+                        deps: hostedDeps(),
+                    });
+                }
+                catch (error) {
+                    if (!(error instanceof PlatformError))
+                        throw error;
+                    fail(`patch --from: ${error.message}`);
+                }
+                patch = from.patch;
+                if (values.json !== true)
+                    process.stderr.write(`carveout: submission ${values.from}: ${from.files} file(s) from ${from.record.base}, on the folder uploaded as version ${from.record.versionId}${from.cutAgain ? ", cut again from the receipt (the folder was gone or edited)" : ""}; judged by the receipt here.\n`);
+            }
+            else {
+                if (dir === undefined)
+                    fail("patch needs the folder a cut wrote, or --from <submission id>.");
+                const given = repoFor(dir);
+                patch = await patchProject(dir, {
+                    ...(given === undefined ? {} : { repo: given }),
+                    ...(values.allow === undefined ? {} : { allow: values.allow }),
+                    ...receiptOption,
+                });
+            }
             const boundary = new Set(patch.boundary.map((edit) => edit.path));
             const notes = [
                 ...(patch.recordFrom === "folder"

package/dist/src/hosted.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The hosted round trip, on the platform (sandbox-factory) a workspace
+ * signed in to with `carveout login` (`platform.ts`):
+ *
+ *   handoff --platform --bounty <id>
+ *     After the local cut and check, the folder, which must be ready,
+ *     public and in pseudonyms, is uploaded with the owner's acceptance
+ *     tests renamed into the folder's names by the receipt's table:
+ *     POST /api/v1/orgs/:org/sandboxes/uploads, under an Idempotency-Key.
+ *     The platform hosts it as a draft version of the bounty, its baseline
+ *     run with every acceptance test failing, and grades contributors'
+ *     submissions against it. What was uploaded is recorded in
+ *     `CARVEOUT_HOME/platform/<cut id>.json`. Publishing the version is a
+ *     person's act in the platform's web app.
+ *
+ *   patch --from <submission id>
+ *     GET /api/v1/orgs/:org/sandboxes/submissions/:sid/files: a passing
+ *     submission's changed files. They are laid over a scratch copy of the
+ *     folder (cut again from the receipt at the cut's commit when the
+ *     folder is gone or edited), and `patchProject` judges that copy with
+ *     the local receipt exactly as `patch <dir>` judges a folder that came
+ *     back by hand.
+ *
+ * What leaves this machine is the folder and the renamed acceptance tests:
+ * never the receipt, its table, or a file outside the folder. The platform
+ * refuses a folder that holds the workspace's names or a credential.
+ * `carveout/api` never imports this module.
+ */
+import { type Patch } from "./carve.js";
+/** An upload is large and is checked before it is answered. */
+export declare const UPLOAD_TIMEOUT_MS = 180000;
+export declare const PLATFORM_RECORD_SCHEMA_VERSION = 1;
+/** The outside world the two commands use; tests pass their own. */
+export interface HostedDeps {
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetchImpl: typeof fetch;
+    readonly now: () => number;
+}
+/** What `handoff --platform` uploaded, kept beside the receipts: never sent. */
+export interface PlatformRecord {
+    readonly schemaVersion: typeof PLATFORM_RECORD_SCHEMA_VERSION;
+    readonly base: string;
+    readonly org: string;
+    readonly bountyId: string;
+    readonly sandboxId: string;
+    readonly versionId: string;
+    readonly runId: string;
+    /** The receipt file, absolute. */
+    readonly receipt: string;
+    /** The folder uploaded, absolute. */
+    readonly folder: string;
+    /** The hash of the folder's carveout.json as uploaded: how a submission is matched to it. */
+    readonly recordSha256: string;
+    readonly cutId: string;
+    readonly uploadedAt: string;
+}
+/** Where uploads are recorded: `CARVEOUT_HOME/platform`. */
+export declare const platformRecordDir: () => string;
+/** The upload whose folder record hashes to `recordSha256`, or null. */
+export declare function findPlatformRecord(recordSha256: string): PlatformRecord | null;
+/**
+ * Every file of a folder as text, at its folder path: none under
+ * node_modules or .git, nor a tool's folder at the root (`TOOL_DIRS`). A
+ * binary file or a link is refused, never sent as something else.
+ */
+export declare function folderFiles(folder: string): {
+    path: string;
+    text: string;
+}[];
+/**
+ * Uploads a folder `handoff` cut and checked: refused unless it is public
+ * and in pseudonyms, with at least one acceptance test, each of which maps
+ * into the folder's names byte for byte. Answers what it recorded.
+ */
+export declare function handoffPlatform(input: {
+    /** `--platform`'s value; else LUNOX_PLATFORM_URL, else production. */
+    readonly platform?: string | undefined;
+    readonly bountyId: string;
+    readonly folder: string;
+    readonly receiptPath: string;
+    /** The owner's acceptance tests, at their repository paths. */
+    readonly accepted: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+    readonly title?: string | undefined;
+    readonly deps: HostedDeps;
+}): Promise<PlatformRecord & {
+    readonly recordPath: string;
+    readonly files: number;
+}>;
+/**
+ * `patch --from`: a passing submission's files, from the platform, laid
+ * over a copy of the folder that was uploaded and judged by the local
+ * receipt (`patchProject`). The copy is removed after.
+ */
+export declare function patchFrom(input: {
+    readonly platform?: string | undefined;
+    readonly submissionId: string;
+    readonly repo?: string | undefined;
+    readonly allow?: readonly string[] | undefined;
+    readonly deps: HostedDeps;
+}): Promise<{
+    readonly patch: Patch;
+    readonly record: PlatformRecord;
+    readonly files: number;
+    readonly cutAgain: boolean;
+}>;

package/dist/src/hosted.js

@@ -0,0 +1,302 @@
+/**
+ * The hosted round trip, on the platform (sandbox-factory) a workspace
+ * signed in to with `carveout login` (`platform.ts`):
+ *
+ *   handoff --platform --bounty <id>
+ *     After the local cut and check, the folder, which must be ready,
+ *     public and in pseudonyms, is uploaded with the owner's acceptance
+ *     tests renamed into the folder's names by the receipt's table:
+ *     POST /api/v1/orgs/:org/sandboxes/uploads, under an Idempotency-Key.
+ *     The platform hosts it as a draft version of the bounty, its baseline
+ *     run with every acceptance test failing, and grades contributors'
+ *     submissions against it. What was uploaded is recorded in
+ *     `CARVEOUT_HOME/platform/<cut id>.json`. Publishing the version is a
+ *     person's act in the platform's web app.
+ *
+ *   patch --from <submission id>
+ *     GET /api/v1/orgs/:org/sandboxes/submissions/:sid/files: a passing
+ *     submission's changed files. They are laid over a scratch copy of the
+ *     folder (cut again from the receipt at the cut's commit when the
+ *     folder is gone or edited), and `patchProject` judges that copy with
+ *     the local receipt exactly as `patch <dir>` judges a folder that came
+ *     back by hand.
+ *
+ * What leaves this machine is the folder and the renamed acceptance tests:
+ * never the receipt, its table, or a file outside the folder. The platform
+ * refuses a folder that holds the workspace's names or a credential.
+ * `carveout/api` never imports this module.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { CARVEOUT_VERSION, RECORD_PATH, carveoutHome, cutSlice, isTextContent, patchProject } from "./carve.js";
+import { TOOL_DIRS } from "./core.js";
+import { assertSafePath } from "./policy.js";
+import { exactToFolder } from "./pseudonyms/index.js";
+import { folderView, readReceipt } from "./receipt.js";
+import { credentialFor, credentialsPath, platformUrl, PlatformError, request } from "./platform.js";
+const CLIENT = "carveout";
+/** An upload is large and is checked before it is answered. */
+export const UPLOAD_TIMEOUT_MS = 180_000;
+export const PLATFORM_RECORD_SCHEMA_VERSION = 1;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** Where uploads are recorded: `CARVEOUT_HOME/platform`. */
+export const platformRecordDir = () => join(carveoutHome(), "platform");
+/** Writes a platform record where only its owner reads it, whole. */
+function writePlatformRecord(record) {
+    const dir = platformRecordDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = join(dir, `${record.cutId}.json`);
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, target);
+    return target;
+}
+/** The upload whose folder record hashes to `recordSha256`, or null. */
+export function findPlatformRecord(recordSha256) {
+    const dir = platformRecordDir();
+    if (!existsSync(dir))
+        return null;
+    for (const name of readdirSync(dir).filter((entry) => entry.endsWith(".json")).sort()) {
+        try {
+            const record = JSON.parse(readFileSync(join(dir, name), "utf8"));
+            if (record.schemaVersion === PLATFORM_RECORD_SCHEMA_VERSION && record.recordSha256 === recordSha256)
+                return record;
+        }
+        catch {
+            // Not one of ours; another is looked at.
+        }
+    }
+    return null;
+}
+/**
+ * Every file of a folder as text, at its folder path: none under
+ * node_modules or .git, nor a tool's folder at the root (`TOOL_DIRS`). A
+ * binary file or a link is refused, never sent as something else.
+ */
+export function folderFiles(folder) {
+    const root = resolve(folder);
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(join(root, dir), { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+            if (entry.name === "node_modules" || entry.name === ".git" || (dir === "" && TOOL_DIRS.includes(entry.name)))
+                continue;
+            const stat = lstatSync(join(root, path));
+            if (stat.isSymbolicLink())
+                throw new PlatformError(`${path} is a link; a folder uploaded holds files only.`);
+            if (stat.isDirectory())
+                walk(path);
+            else if (stat.isFile()) {
+                const bytes = readFileSync(join(root, path));
+                if (!isTextContent(bytes))
+                    throw new PlatformError(`${path} is not UTF-8 text; the platform takes a folder of text files only.`);
+                files.push({ path, text: bytes.toString("utf8") });
+            }
+        }
+    };
+    walk("");
+    return files;
+}
+/** This CLI's saved sign-in for `base`, or a PlatformError saying how to get one. */
+function signedIn(base, env) {
+    const saved = credentialFor(credentialsPath(env), base, CLIENT);
+    if (saved === undefined)
+        throw new PlatformError(`Not signed in to ${base}. Run \`carveout login\`.`);
+    return saved;
+}
+/**
+ * Uploads a folder `handoff` cut and checked: refused unless it is public
+ * and in pseudonyms, with at least one acceptance test, each of which maps
+ * into the folder's names byte for byte. Answers what it recorded.
+ */
+export async function handoffPlatform(input) {
+    const base = platformUrl(input.platform, input.deps.env);
+    const saved = signedIn(base, input.deps.env);
+    const receipt = readReceipt(input.receiptPath);
+    const table = receipt.pseudonyms;
+    const view = folderView(receipt);
+    if (table === undefined || view.publicScrubbed !== true || view.request.public !== true)
+        throw new PlatformError("Only a public folder in pseudonyms is uploaded: hand off without --keep-names or --no-public, so the platform never has the repository's names.");
+    if (input.accepted.length === 0)
+        throw new PlatformError("The platform grades a submission by the owner's acceptance tests: hand off with --accept <test>..., tests that fail before the work.");
+    const acceptanceTests = input.accepted.map((test) => {
+        const folder = exactToFolder(table, test.path, test.text);
+        if (folder === null)
+            throw new PlatformError(`${test.path} would not map into the folder's names byte for byte; rename what it names, and hand off again.`);
+        return { path: folder.path, text: folder.text, expectedBaseline: "fail" };
+    });
+    const files = folderFiles(input.folder);
+    const recordText = files.find((file) => file.path === RECORD_PATH)?.text;
+    if (recordText === undefined)
+        throw new PlatformError(`${input.folder} has no ${RECORD_PATH}; it was not cut by carveout.`);
+    const own = JSON.parse(recordText);
+    if (own.cutId !== receipt.cutId)
+        throw new PlatformError(`${input.folder} is not the folder of cut ${receipt.cutId.slice(0, 8)}, whose receipt was given.`);
+    const recordSha256 = sha256(recordText);
+    const answer = await request({
+        base,
+        method: "POST",
+        path: `/api/v1/orgs/${encodeURIComponent(saved.organizationId)}/sandboxes/uploads`,
+        token: saved.token,
+        client: CLIENT,
+        version: CARVEOUT_VERSION,
+        fetchImpl: input.deps.fetchImpl,
+        idempotencyKey: randomUUID(),
+        timeoutMs: UPLOAD_TIMEOUT_MS,
+        body: {
+            bountyId: input.bountyId,
+            carveout: { version: CARVEOUT_VERSION, recordSha256 },
+            files,
+            acceptanceTests,
+            ...(input.title === undefined ? {} : { title: input.title }),
+        },
+    });
+    const id = (value) => (typeof value?.id === "string" ? value.id : null);
+    const [sandboxId, versionId, runId] = [id(answer.sandbox), id(answer.version), id(answer.run)];
+    if (sandboxId === null || versionId === null || runId === null)
+        throw new PlatformError(`${base} took the upload but answered without its sandbox, version and run.`);
+    const record = {
+        schemaVersion: PLATFORM_RECORD_SCHEMA_VERSION,
+        base,
+        org: saved.organizationId,
+        bountyId: input.bountyId,
+        sandboxId,
+        versionId,
+        runId,
+        receipt: resolve(input.receiptPath),
+        folder: resolve(input.folder),
+        recordSha256,
+        cutId: receipt.cutId,
+        uploadedAt: new Date(input.deps.now()).toISOString(),
+    };
+    return { ...record, recordPath: writePlatformRecord(record), files: files.length };
+}
+/** Whether the folder on disk is the one uploaded, every file the cut wrote unchanged. */
+function folderIntact(folder, receipt, recordSha256) {
+    const at = (path) => join(folder, path);
+    if (!existsSync(at(RECORD_PATH)) || sha256(readFileSync(at(RECORD_PATH))) !== recordSha256)
+        return false;
+    const view = folderView(receipt);
+    return [...(view.copied ?? []), ...view.generated].every((file) => existsSync(at(file.path)) && sha256(readFileSync(at(file.path))) === file.sha256);
+}
+/** The files of a folder, copied to `to`, without what `folderFiles` leaves out. */
+function copyFolder(from, to) {
+    const root = resolve(from);
+    cpSync(root, to, {
+        recursive: true,
+        filter: (source) => {
+            const rel = source === root ? "" : source.slice(root.length + 1).split("\\").join("/");
+            const parts = rel.split("/");
+            return !parts.includes("node_modules") && !parts.includes(".git") && !(parts.length >= 1 && TOOL_DIRS.includes(parts[0] ?? ""));
+        },
+    });
+}
+/**
+ * The folder cut again from the receipt, at the cut's commit, in a clone
+ * of the repository: the copied files as the cut wrote them, the generated
+ * ones and the record as the receipt keeps them. Refused unless every file
+ * is the one uploaded.
+ */
+async function cutAgain(receipt, scratch, out, recordSha256) {
+    const record = receipt.record;
+    const commit = record.manifest.sourceCommitSha;
+    if (commit === null || !existsSync(receipt.repo))
+        throw new PlatformError(`The folder ${receipt.out} is gone or edited, and the cut cannot be made again (${commit === null ? "it was not cut at a commit" : `${receipt.repo} is gone`}): restore the folder as it was uploaded.`);
+    const repo = join(scratch, "repo");
+    const git = (cwd, args) => execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    git(scratch, ["clone", "-q", "--shared", "--no-checkout", receipt.repo, repo]);
+    git(repo, ["checkout", "-q", "--detach", commit]);
+    const request = record.request;
+    await cutSlice({
+        repo,
+        out,
+        entryPoints: request.entryPoints,
+        budget: request.budget,
+        choices: request.choices,
+        offline: true,
+        widenLiterals: request.widenLiterals,
+        tests: request.tests === true,
+        ...(request.live === undefined ? {} : { live: request.live }),
+        wholePackage: request.wholePackage === true,
+        followWorkspaces: request.followWorkspaces === true,
+        copyPure: request.copyPure === true,
+        private: request.private ?? [],
+        copy: request.copy ?? [],
+        public: true,
+        ...(request.task === undefined ? {} : { task: request.task }),
+        ...(receipt.pseudonyms === undefined ? {} : { earlierPseudonyms: receipt.pseudonyms, names: receipt.pseudonyms.vocabulary }),
+        ...(receipt.unseen === undefined ? {} : { unseen: receipt.unseen }),
+        receipt: join(scratch, "receipt.json"),
+        log: () => { },
+    });
+    // What the cut generated, and its record, as the folder held them.
+    for (const [path, text] of Object.entries(receipt.generatedText ?? {})) {
+        assertSafePath(path, "a generated file");
+        mkdirSync(dirname(join(out, path)), { recursive: true });
+        writeFileSync(join(out, path), text);
+    }
+    writeFileSync(join(out, RECORD_PATH), `${JSON.stringify(folderView(receipt), null, 2)}\n`);
+    if (!folderIntact(out, receipt, recordSha256))
+        throw new PlatformError(`The folder ${receipt.out} is gone or edited, and cut again from the receipt it is not the folder uploaded: restore the folder as it was uploaded.`);
+}
+/**
+ * `patch --from`: a passing submission's files, from the platform, laid
+ * over a copy of the folder that was uploaded and judged by the local
+ * receipt (`patchProject`). The copy is removed after.
+ */
+export async function patchFrom(input) {
+    const base = platformUrl(input.platform, input.deps.env);
+    const saved = signedIn(base, input.deps.env);
+    const answer = await request({
+        base,
+        path: `/api/v1/orgs/${encodeURIComponent(saved.organizationId)}/sandboxes/submissions/${encodeURIComponent(input.submissionId)}/files`,
+        token: saved.token,
+        client: CLIENT,
+        version: CARVEOUT_VERSION,
+        fetchImpl: input.deps.fetchImpl,
+    });
+    const recordSha256 = answer.upload?.recordSha256;
+    const files = answer.files;
+    if (typeof recordSha256 !== "string" ||
+        !Array.isArray(files) ||
+        !files.every((file) => typeof file.path === "string" && typeof file.text === "string"))
+        throw new PlatformError(`${base} answered submission ${input.submissionId} without its files.`);
+    const record = findPlatformRecord(recordSha256);
+    if (record === null)
+        throw new PlatformError(`Submission ${input.submissionId} is on a folder this machine did not upload (no record under ${platformRecordDir()}): run patch --from where handoff --platform ran.`);
+    if (!existsSync(record.receipt))
+        throw new PlatformError(`${record.receipt}: the receipt of that hand-off is gone.`);
+    const receipt = readReceipt(record.receipt);
+    const scratch = mkdtempSync(join(tmpdir(), "carveout-from-"));
+    try {
+        const dir = join(scratch, "folder");
+        const intact = folderIntact(record.folder, receipt, recordSha256);
+        if (intact)
+            copyFolder(record.folder, dir);
+        else
+            await cutAgain(receipt, scratch, dir, recordSha256);
+        for (const file of files) {
+            try {
+                assertSafePath(file.path, "a submitted file");
+            }
+            catch {
+                throw new PlatformError(`${base} answered a file at ${JSON.stringify(file.path)}, which is not a plain path in the folder.`);
+            }
+            mkdirSync(dirname(join(dir, file.path)), { recursive: true });
+            writeFileSync(join(dir, file.path), file.text);
+        }
+        const patch = await patchProject(dir, {
+            receipt: record.receipt,
+            ...(input.repo === undefined ? {} : { repo: input.repo }),
+            ...(input.allow === undefined ? {} : { allow: input.allow }),
+        });
+        return { patch, record, files: files.length, cutAgain: !intact };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/dist/src/platform.d.ts

@@ -3,7 +3,8 @@
  * talks to it: the base URL, the shared credentials file, and one request
  * function on `fetch`, so carveout keeps `typescript` as its only
  * dependency. Nothing here runs unless a platform command (`login`,
- * `whoami`, `logout`, in `account.ts`) is called; every other command stays
+ * `whoami`, `logout`, in `account.ts`; `handoff --platform` and
+ * `patch --from`, in `hosted.ts`) is called; every other command stays
  * local, and `carveout/api` never imports it.
  *
  * Credentials: `~/.lunox/credentials` (LUNOX_CREDENTIALS moves it), JSON,
@@ -57,6 +58,10 @@ export interface RequestOptions {
     readonly session?: boolean;
     readonly body?: unknown;
     readonly fetchImpl?: typeof fetch;
+    /** Sent as `Idempotency-Key`: a retried create gets its first answer back. */
+    readonly idempotencyKey?: string;
+    /** How long the call may take; 30 seconds unless given (an upload takes longer). */
+    readonly timeoutMs?: number;
 }
 /**
  * One call to the platform's API. Sends the token as a bearer, the client

package/dist/src/platform.js

@@ -3,7 +3,8 @@
  * talks to it: the base URL, the shared credentials file, and one request
  * function on `fetch`, so carveout keeps `typescript` as its only
  * dependency. Nothing here runs unless a platform command (`login`,
- * `whoami`, `logout`, in `account.ts`) is called; every other command stays
+ * `whoami`, `logout`, in `account.ts`; `handoff --platform` and
+ * `patch --from`, in `hosted.ts`) is called; every other command stays
  * local, and `carveout/api` never imports it.
  *
  * Credentials: `~/.lunox/credentials` (LUNOX_CREDENTIALS moves it), JSON,
@@ -126,7 +127,7 @@ function minimumOf(body) {
  * upgrade, otherwise the API's own `{ error, code }`.
  */
 export async function request(options) {
-    const { base, path, client, version, method = "GET", token, session = false, body, fetchImpl = fetch } = options;
+    const { base, path, client, version, method = "GET", token, session = false, body, fetchImpl = fetch, idempotencyKey, timeoutMs = 30_000, } = options;
     const headers = {
         Accept: "application/json",
         "User-Agent": `${client}/${version}`,
@@ -136,6 +137,8 @@ export async function request(options) {
         headers["Authorization"] = `Bearer ${token}`;
     if (body !== undefined)
         headers["Content-Type"] = "application/json";
+    if (idempotencyKey !== undefined)
+        headers["Idempotency-Key"] = idempotencyKey;
     let response;
     try {
         response = await fetchImpl(`${base}${path}`, {
@@ -143,7 +146,7 @@ export async function request(options) {
             headers,
             ...(body === undefined ? {} : { body: JSON.stringify(body) }),
             redirect: "error",
-            signal: AbortSignal.timeout(30_000),
+            signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carveout",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Hand one part of a closed TypeScript repository to an outside contractor: a slice, stubbed and mocked, that installs, builds and tests on its own, and a checked patch back. Also checks a change made in the repository: what it reaches, the tests to run, and weakened tests or config edits.",
   "keywords": [
     "carveout",

package/skills/carveout/SKILL.md

@@ -17,14 +17,14 @@ description: >-
 license: MIT
 compatibility: >-
   Node 22.12 or later, git and npm; Docker to run a returned folder's code. Runs
-  the carveout@0.3.1 CLI from npm; online cuts read the npm registry.
+  the carveout@0.4.0 CLI from npm; online cuts read the npm registry.
 ---
 
 # carveout
 
-`carveout <command>` is the CLI, `carveout@0.3.1`. When `carveout --version`
+`carveout <command>` is the CLI, `carveout@0.4.0`. When `carveout --version`
 prints another version or nothing, ask the person before installing it:
-`npm i -g carveout@0.3.1`, or put `npx carveout@0.3.1` in place of `carveout` in
+`npm i -g carveout@0.4.0`, or put `npx carveout@0.4.0` in place of `carveout` in
 each command (in a clone of the repository, `node dist/src/cli.js` after
 `npm install && npm run build`). Node 22.12 or later, and `git` and `npm` on
 PATH.
@@ -71,16 +71,18 @@ kept. The sections below are each step in full.
 
 With the `lunox` MCP tools signed in (bundled; `/mcp` signs in), read with the
 `list_*`/`get_*` tools. Write only when asked: a bounty (`post_bounty` or
-`import_github_issue`, `size_bounty` is a paid run, `get_decisions` and
-`confirm_link`), a slice (`plan_slice`, `start_sandbox`, `cut_slice`), its
-build (`prepare`, then `get_handout`: public files and the hidden suite's hash
-only), a contractor's patch (`submit_patch`, `get_verdict`, one `retry`).
-Approvals, decisions, publishing and merging back happen in the web app. Model
-runs (`size_bounty`, `prepare`, `retry`) count against a monthly token limit
-(`get_usage`); on `quota_exceeded`, tell the person when it resets and do not
-retry. `insufficient_scope` means signing in again through `/mcp`. Never ask
-for a token; the CLI signs in with `carveout login`. Local mode, below, is the
-default.
+`import_github_issue`; `size_bounty` is a paid run; `get_decisions`,
+`confirm_link`), a slice (`plan_slice`, `start_sandbox`, `cut_slice`), its build
+(`prepare`, then `get_handout`: public files and the hidden suite's hash only),
+a contractor's patch (`submit_patch`, `get_verdict`, one `retry`). Approvals,
+decisions, publishing and merging back happen in the web app. Model runs
+(`size_bounty`, `prepare`, `retry`) count against a monthly token limit
+(`get_usage`); on `quota_exceeded`, say when it resets and do not retry. On
+`insufficient_scope`, sign in again through `/mcp`. Never ask for a token; the
+CLI signs in with `carveout login`. For an unconnected repository, `handoff ...
+--accept <test>... --platform --bounty <id>` uploads the ready folder and the
+tests in its names, never the receipt; `patch --from <submission id>` judges a
+passing submission by the local receipt. Local mode, below, is the default.
 
 ## 1. Plan
 
@@ -121,12 +123,10 @@ The defaults are depth 3 and 40 files. Choose the budget with the person:
 
 Depth counts imports of code. Going through a barrel's re-export does not add
 depth, and only the module that declares an imported name comes along, not the
-barrel's other modules. A module the slice imports only types from is always cut
-to a stub.
+barrel's other modules. A module the slice takes only types from is a stub.
 
-When the file limit is reached, the plan lists the files it left out. Raise
-`--max-files`, or narrow the entry points. `--json` gives the same report as
-data.
+At the file limit, the plan lists the files it left out: raise `--max-files`,
+or narrow the entry points. `--json` gives the same report as data.
 
 `--with-tests` also brings the test files outside the slice that import it
 (`*.test.*`, `*.spec.*`, `__tests__/`), when they run on `node:test` or Vitest

package/skills/carveout-gate/SKILL.md

@@ -14,7 +14,7 @@ description: >-
   test to make it pass.
 license: MIT
 compatibility: >-
-  Node 22.12 or later, git and npm. Runs the carveout@0.3.1 CLI from npm.
+  Node 22.12 or later, git and npm. Runs the carveout@0.4.0 CLI from npm.
 ---
 
 # carveout-gate
@@ -23,9 +23,9 @@ What a change made in the repository reaches, and whether it weakened the checks
 that would catch it. To hand a part of the repository to someone outside it
 instead, use the `carveout` skill.
 
-`carveout <command>` is the CLI, `carveout@0.3.1`. When `carveout --version`
+`carveout <command>` is the CLI, `carveout@0.4.0`. When `carveout --version`
 prints another version or nothing, ask the person before installing it:
-`npm i -g carveout@0.3.1`, or put `npx carveout@0.3.1` in place of `carveout` in
+`npm i -g carveout@0.4.0`, or put `npx carveout@0.4.0` in place of `carveout` in
 each command (in a clone of the repository, `node dist/src/cli.js` after
 `npm install && npm run build`). Node 22.12 or later, and `git` and `npm` on
 PATH.