carveout 0.1.0 → 0.1.2

package/dist/src/platform.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The hosted platform (sandbox-factory, platform.lunox.work) as this CLI
+ * 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
+ * local, and `carveout/api` never imports it.
+ *
+ * Credentials: `~/.lunox/credentials` (LUNOX_CREDENTIALS moves it), JSON,
+ * mode 600 in a 700 folder, written whole through a rename. duediligence
+ * shares the file, so each CLI keeps its own entry under the platform's URL:
+ *
+ *   { "https://platform.lunox.work": {
+ *       "carveout": { token, organizationId, organizationHandle, client, createdAt, expiresAt },
+ *       "duediligence": { ... } } }
+ *
+ * A token is minted for one client with that client's scopes, so the two
+ * CLIs never share one; writing an entry keeps every other.
+ */
+export declare const DEFAULT_PLATFORM = "https://platform.lunox.work";
+export interface Credential {
+    readonly token: string;
+    readonly organizationId: string;
+    readonly organizationHandle: string;
+    readonly client: string;
+    readonly createdAt: string;
+    readonly expiresAt: string | null;
+}
+type CredentialsFile = Record<string, Record<string, unknown>>;
+export declare class PlatformError extends Error {
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, details?: {
+        status?: number;
+        code?: string | undefined;
+    });
+}
+/** `--platform`, else LUNOX_PLATFORM_URL, else production; no trailing slash. HTTPS, or plain HTTP to this machine only. */
+export declare function platformUrl(given: string | undefined, env?: NodeJS.ProcessEnv): string;
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+/** The whole file, `{}` when there is none. A file that is not a JSON object is refused, never overwritten. */
+export declare function readCredentials(path: string): CredentialsFile;
+/** Writes the file whole: a 600 temp file beside it, renamed over it. Removes it when nothing is left. */
+export declare function writeCredentials(path: string, all: CredentialsFile): void;
+/** This client's entry for a platform, or undefined. */
+export declare function credentialFor(path: string, base: string, client: string): Credential | undefined;
+/** Sets (or, with `entry` undefined, removes) this client's entry, keeping every other. */
+export declare function saveCredential(path: string, base: string, client: string, entry: Credential | undefined): void;
+export interface RequestOptions {
+    readonly base: string;
+    readonly path: string;
+    readonly client: string;
+    readonly version: string;
+    readonly method?: string;
+    readonly token?: string | undefined;
+    /** The token is a device sign-in's session rather than a saved API token. */
+    readonly session?: boolean;
+    readonly body?: unknown;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * One call to the platform's API. Sends the token as a bearer, the client
+ * and its version as `User-Agent` and `Lunox-Client-Version`
+ * (`<client>/<version>`), and JSON. Answers the parsed body; throws a
+ * PlatformError whose message says what to do: 401 → sign in again, 426 →
+ * upgrade, otherwise the API's own `{ error, code }`.
+ */
+export declare function request<T = Record<string, unknown>>(options: RequestOptions): Promise<T>;
+export {};

package/dist/src/platform.js

@@ -0,0 +1,184 @@
+/**
+ * The hosted platform (sandbox-factory, platform.lunox.work) as this CLI
+ * 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
+ * local, and `carveout/api` never imports it.
+ *
+ * Credentials: `~/.lunox/credentials` (LUNOX_CREDENTIALS moves it), JSON,
+ * mode 600 in a 700 folder, written whole through a rename. duediligence
+ * shares the file, so each CLI keeps its own entry under the platform's URL:
+ *
+ *   { "https://platform.lunox.work": {
+ *       "carveout": { token, organizationId, organizationHandle, client, createdAt, expiresAt },
+ *       "duediligence": { ... } } }
+ *
+ * A token is minted for one client with that client's scopes, so the two
+ * CLIs never share one; writing an entry keeps every other.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_PLATFORM = "https://platform.lunox.work";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export class PlatformError extends Error {
+    status;
+    code;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = "PlatformError";
+        this.status = details.status;
+        this.code = details.code;
+    }
+}
+/** `--platform`, else LUNOX_PLATFORM_URL, else production; no trailing slash. HTTPS, or plain HTTP to this machine only. */
+export function platformUrl(given, env = process.env) {
+    const raw = given ?? env["LUNOX_PLATFORM_URL"] ?? DEFAULT_PLATFORM;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new PlatformError(`${raw} is not a URL.`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+        throw new PlatformError(`${raw}: the platform must be https:// (plain http only on localhost).`);
+    }
+    url.search = "";
+    url.hash = "";
+    return url.href.replace(/\/+$/, "");
+}
+export function credentialsPath(env = process.env) {
+    return env["LUNOX_CREDENTIALS"] ?? join(homedir(), ".lunox", "credentials");
+}
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** The whole file, `{}` when there is none. A file that is not a JSON object is refused, never overwritten. */
+export function readCredentials(path) {
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new PlatformError(`${path} is not valid JSON (${error.message}); fix or remove it.`);
+    }
+    if (!isObject(parsed))
+        throw new PlatformError(`${path} does not hold a JSON object; fix or remove it.`);
+    return parsed;
+}
+/** Writes the file whole: a 600 temp file beside it, renamed over it. Removes it when nothing is left. */
+export function writeCredentials(path, all) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+    }
+    if (Object.keys(all).length === 0) {
+        rmSync(path, { force: true });
+        return;
+    }
+    const temp = join(dir, `.credentials-${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        writeFileSync(temp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        chmodSync(temp, 0o600);
+        renameSync(temp, path);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+/** This client's entry for a platform, or undefined. */
+export function credentialFor(path, base, client) {
+    const entry = readCredentials(path)[base]?.[client];
+    return isObject(entry) && typeof entry["token"] === "string" ? entry : undefined;
+}
+/** Sets (or, with `entry` undefined, removes) this client's entry, keeping every other. */
+export function saveCredential(path, base, client, entry) {
+    const all = readCredentials(path);
+    const forBase = { ...(isObject(all[base]) ? all[base] : {}) };
+    if (entry === undefined)
+        delete forBase[client];
+    else
+        forBase[client] = entry;
+    if (Object.keys(forBase).length === 0)
+        delete all[base];
+    else
+        all[base] = forBase;
+    writeCredentials(path, all);
+}
+/** The minimum version a 426 names, wherever the body puts it. */
+function minimumOf(body) {
+    const named = body?.["minimumVersion"] ?? body?.["minimum_version"] ?? body?.["minimum"];
+    if (typeof named === "string")
+        return named;
+    const said = body?.["error"];
+    return typeof said === "string" ? /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/.exec(said)?.[0] : undefined;
+}
+/**
+ * One call to the platform's API. Sends the token as a bearer, the client
+ * and its version as `User-Agent` and `Lunox-Client-Version`
+ * (`<client>/<version>`), and JSON. Answers the parsed body; throws a
+ * PlatformError whose message says what to do: 401 → sign in again, 426 →
+ * 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 headers = {
+        Accept: "application/json",
+        "User-Agent": `${client}/${version}`,
+        "Lunox-Client-Version": `${client}/${version}`,
+    };
+    if (token !== undefined)
+        headers["Authorization"] = `Bearer ${token}`;
+    if (body !== undefined)
+        headers["Content-Type"] = "application/json";
+    let response;
+    try {
+        response = await fetchImpl(`${base}${path}`, {
+            method,
+            headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            redirect: "error",
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        const cause = error.cause?.message;
+        throw new PlatformError(`Could not reach ${base}: ${cause ?? error.message}`);
+    }
+    const text = await response.text();
+    let parsed;
+    try {
+        const value = text === "" ? undefined : JSON.parse(text);
+        parsed = isObject(value) ? value : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (response.ok)
+        return (parsed ?? {});
+    const status = response.status;
+    const error = parsed?.["error"];
+    const code = typeof parsed?.["code"] === "string"
+        ? parsed["code"]
+        : typeof error === "string" && !error.includes(" ")
+            ? error
+            : undefined;
+    if (status === 426) {
+        const minimum = minimumOf(parsed);
+        throw new PlatformError(`${base} needs a newer ${client}${minimum ? `: upgrade to at least ${minimum}` : ""} (this is ${version}). npm i -g ${client}@latest`, { status, code });
+    }
+    if (status === 401 && token !== undefined) {
+        const what = session ? "The browser sign-in" : "The saved sign-in";
+        throw new PlatformError(`${what} for ${base} is no longer valid (expired or revoked). Run \`${client} login\` again.`, {
+            status,
+            code,
+        });
+    }
+    const said = parsed?.["error_description"] ?? error ?? parsed?.["message"];
+    throw new PlatformError(typeof said === "string" ? `${said}${code && code !== said ? ` (${code})` : ""}` : `${method} ${path}: HTTP ${status}`, { status, code });
+}

package/dist/src/policy.d.ts

@@ -0,0 +1,181 @@
+/**
+ * What a folder handed to someone outside may bring back.
+ *
+ * A folder comes back from a contributor the repository does not trust, so
+ * nothing in it is taken on its word: the paths its `carveout.json` names
+ * must stay inside the folder and the repository, the repository is the one
+ * the maintainer names (or the one the record names, checked to hold the
+ * cut's commit), and the patch carries only what a change to the slice can
+ * honestly need. New files outside the slice's packages, files that run on
+ * someone's machine or in CI without a review of code (workflows, hooks,
+ * manifests, lockfiles, environment), deleted tests and tests whose
+ * assertions were removed, rewritten or skipped are left out and named,
+ * unless the maintainer allows them by path or glob.
+ */
+import { weakenedTest } from "./test-integrity.js";
+/**
+ * Paths a patch from a slice never carries unless allowed: they run in CI
+ * with its secrets, on a maintainer's machine (hooks, editor tasks), at
+ * install (manifests, lockfiles, registry configuration), or hold
+ * configuration a change to code does not need.
+ */
+export declare const PROTECTED_PATHS: readonly string[];
+/**
+ * Throws unless `path` is a plain relative path that stays where it is
+ * joined: `/`-separated, not absolute, no `.` or `..` segment, no `.git`.
+ */
+export declare function assertSafePath(path: unknown, what: string): asserts path is string;
+/** What `checkRecordPaths` reads of a record. */
+interface RecordPaths {
+    readonly manifest: {
+        readonly included: readonly {
+            readonly path: unknown;
+        }[];
+    };
+    readonly generated: readonly {
+        readonly path: unknown;
+    }[];
+    readonly copied?: readonly {
+        readonly path: unknown;
+    }[];
+    readonly extras?: readonly {
+        readonly path: unknown;
+    }[];
+    readonly importRewrites: readonly {
+        readonly file: unknown;
+    }[];
+    readonly request: {
+        readonly entryPoints: readonly unknown[];
+    };
+}
+/** Every path a record makes carveout read, write or delete, checked. */
+export declare function checkRecordPaths(record: RecordPaths): void;
+/**
+ * The checkout to diff and apply against: the one the maintainer names, else
+ * the record's. Either way it must be a folder that holds the cut's commit,
+ * so a record cannot point carveout at another folder of the machine.
+ */
+export declare function trustedRepo(record: {
+    readonly repo?: string | null;
+    readonly manifest: {
+        readonly sourceCommitSha: string | null;
+    };
+}, given: string | undefined): string;
+export interface Refusal {
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * Configuration that decides what a check holds code to: compiler, linter
+ * and test-runner settings. A change that loosens one makes every check
+ * after it pass more, so `gate` names it for a review.
+ */
+export declare const CHECK_CONFIG_PATHS: readonly string[];
+/**
+ * How many check suppressions a script's text holds. A test's
+ * `@ts-expect-error` asserts that a call does not type-check, which is a
+ * test of the types, not a suppression.
+ */
+export declare function suppressionsOf(text: string, path?: string): number;
+/**
+ * Judges each path a patch would carry. `packages` are the repository's
+ * package folders the slice holds files of ("" for the root package);
+ * `allow` are the maintainer's paths and globs that pass whatever the rule.
+ */
+export declare function handoffPolicy(options: {
+    /** Without it, a new file may go anywhere. */
+    readonly packages?: ReadonlySet<string>;
+    readonly packageOf?: (path: string) => string;
+    readonly allow?: readonly string[];
+    /**
+     * Also refuse what loosens a check: an edit to compiler, linter or
+     * test-runner configuration, and a script that gains suppressions
+     * (`@ts-ignore`, `eslint-disable`, coverage ignores). `gate` turns it on.
+     */
+    readonly checks?: boolean;
+    /** How a refusal names a test: "a test the slice was handed" by default. */
+    readonly testNoun?: string;
+    /**
+     * Also refuse a script that gains a reach it did not have: the disk, the
+     * network, the process or its environment, a service SDK, or code loaded
+     * by a computed name (`reachOf`). A returned test or module runs beside
+     * the whole repository, the closed part included, so `patch` turns it on.
+     */
+    readonly reach?: boolean;
+    /**
+     * Also refuse a script that gains a way to pass a test without the code
+     * passing it (`integrityOf`): ending the test run early, swallowing its
+     * failures, telling a test run from a real one, rewriting the assertion
+     * library or a built-in. `patch` and `gate` turn it on.
+     */
+    readonly integrity?: boolean;
+    /** Packages the folder installs or mocks: a bare import of another is new reach. */
+    readonly knownPackages?: ReadonlySet<string>;
+    /** Whether a repository path is one the slice holds or stubs; see `ReachContext.holds`. */
+    readonly holds?: (path: string) => boolean;
+    /** Whether a path is a test's helper by what imports it (only tests do). */
+    readonly testSupport?: (path: string) => boolean;
+    /**
+     * Whether a path is a setup file the test runner runs before every test
+     * (Vitest's `setupFiles`): whatever its name, a change to it is a change
+     * to what a check holds code to. A `vi.mock` there replaces the code
+     * under test in every test of the package.
+     */
+    readonly testSetup?: (path: string) => boolean;
+}): (path: string, change: "added" | "changed" | "deleted", texts?: {
+    readonly before: string | null;
+    readonly after: string;
+}) => string | null;
+/** What a script is read against: the packages and package folders the slice has. */
+export interface ReachContext {
+    /** Packages the folder installs or mocks; a bare import of any other is new reach. */
+    readonly knownPackages?: ReadonlySet<string>;
+    /** The slice's package folders, and how a path maps to one. */
+    readonly packages?: ReadonlySet<string>;
+    readonly packageOf?: (path: string) => string;
+    /** Whether a repository path is one the slice holds or stubs already: importing it reaches nothing new. */
+    readonly holds?: (path: string) => boolean;
+}
+/**
+ * What a script reaches beyond its own computation, read from its syntax
+ * and never run: Node modules with the disk, the network or the process
+ * (`node:fs`), service SDKs, a package the slice does not have, a module
+ * outside the slice's packages, network and code-running globals (`fetch`,
+ * `eval`, `Function` by any route), the environment (`process.env`,
+ * `import.meta.env`, `process.report`), the module loader, a file loaded
+ * raw or as native code, and modules or globals named by a computed value
+ * or hidden behind one (`const p = process`), which could be any of these.
+ * Each as a short label, sorted. Text-level: a hold for a reader, not a
+ * sandbox.
+ */
+export declare function reachOf(path: string, text: string, context?: ReachContext): string[];
+/**
+ * How a script could make a test pass without the code under test passing
+ * it, read from its syntax and never run. In any script: ending the
+ * process early with no failing code (`process.exit(0)` before the tests
+ * run reports success; in the code under test, when it loads), listening
+ * for the failures it would otherwise die of (`process.on("uncaughtException",
+ * …)`), rewriting the assertion library or the runner (`assert.equal = …`,
+ * an alias of it, `expect.extend` over a built-in matcher,
+ * `addEqualityTesters`), and rewriting a built-in (`Object.is = …`), which
+ * a test may do only for the clock and the dice (`Date.now`,
+ * `Math.random`). In code that is not a test nor a test's helper: telling
+ * a test run from a real one (`typeof describe`, `import.meta.vitest`,
+ * `process.env.VITEST`, `NODE_ENV === "test"`, `process.argv` matched
+ * against a runner, the stack read for one). `process` and the built-ins
+ * are followed through aliases and casts. Each as a short label, sorted.
+ * Text-level, like `reachOf`: a hold for a reader, not a sandbox.
+ */
+export declare function integrityOf(path: string, text: string): string[];
+/**
+ * The ways to pass a test without the code that a script's new text has
+ * more of than its old text (`integrityOf`), or nothing when it is no script.
+ */
+export declare function gainedIntegrity(path: string, before: string | null, after: string): string[];
+/**
+ * The reach a script's new text has more of than its old text did
+ * (`reachOf`), or nothing when it is no script. A file that already read
+ * the disk may keep doing so: only what the change adds is a question.
+ */
+export declare function gainedReach(path: string, before: string | null, after: string, context?: ReachContext): string[];
+export { weakenedTest };