@catalyst-cloud/cli 0.14.6 → 0.14.8

package/dist/env/onboard-draft-store.js

@@ -0,0 +1,250 @@
+import { createHash } from "node:crypto";
+import { isRepositoryId } from "../repository-id.js";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, unlink } from "node:fs/promises";
+import { isAbsolute, join, parse, resolve, sep } from "node:path";
+import { onboardStateRoot } from "../onboard.js";
+const OPAQUE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const MAX_TOML_BYTES = 1024 * 1024;
+const defaultFs = { mkdir, lstat, open, unlink };
+/**
+ * Persist a private copy of a draft produced and fully validated by the caller. This function
+ * checks the storage boundary only; it does not validate settings or inspect TOML values.
+ */
+export async function storeOnboardDraft(input, fsOps = defaultFs) {
+    const home = input?.home;
+    const env = input?.env;
+    const runId = input?.runId;
+    const repoId = input?.repoId;
+    const toml = input?.toml;
+    const signal = input?.signal;
+    if (typeof runId !== "string" ||
+        !OPAQUE_ID_RE.test(runId) ||
+        !isRepositoryId(repoId) ||
+        typeof home !== "string" ||
+        !isAbsolute(home) ||
+        typeof toml !== "string" ||
+        Buffer.byteLength(toml, "utf8") > MAX_TOML_BYTES ||
+        signal?.aborted)
+        return { state: "rejected" };
+    // Snapshot the expected bytes and resolved paths before the first asynchronous operation.
+    const expected = Buffer.from(toml, "utf8");
+    let stateRoot;
+    let runDir;
+    let destination;
+    try {
+        stateRoot = resolve(onboardStateRoot(home, env));
+        if (stateRoot === parse(stateRoot).root || stateRoot === resolve(home))
+            return { state: "rejected" };
+        runDir = join(stateRoot, "install", "drafts", runId);
+        // Keep earlier slug filenames resumable. New cloud IDs use a portable bounded filename;
+        // punctuation normalization would collide and raw IDs can exceed NAME_MAX.
+        // The @ namespace cannot collide with any earlier slug filename.
+        const filename = OPAQUE_ID_RE.test(repoId)
+            ? `${repoId}.toml`
+            : `repo@${createHash("sha256").update(repoId, "utf8").digest("hex")}.toml`;
+        destination = join(runDir, filename);
+    }
+    catch {
+        return { state: "rejected" };
+    }
+    let handle;
+    let created;
+    try {
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            return { state: "rejected" };
+        try {
+            handle = await fsOps.open(destination, constants.O_WRONLY |
+                constants.O_CREAT |
+                constants.O_EXCL |
+                constants.O_NOFOLLOW, 0o600);
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+            return await resumeExisting(destination, runDir, stateRoot, expected, signal, fsOps);
+        }
+        const opened = await handle.stat();
+        created = { dev: opened.dev, ino: opened.ino };
+        if (!opened.isFile() || opened.nlink !== 1 || !privateMode(opened.mode))
+            throw new Error("unsafe artifact");
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await handle.writeFile(expected);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await handle.sync();
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await verifyCreatedPath(destination, created, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await handle.close();
+        handle = undefined;
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await verifyCreatedPath(destination, created, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        return { state: "stored", path: destination };
+    }
+    catch {
+        if (handle !== undefined) {
+            try {
+                await handle.close();
+            }
+            catch {
+                /* settle close before inode-scoped cleanup */
+            }
+        }
+        if (created !== undefined)
+            await removeCreatedFile(destination, created, fsOps);
+        return { state: "rejected" };
+    }
+}
+async function resumeExisting(path, runDir, stateRoot, expected, signal, fsOps) {
+    let handle;
+    try {
+        if (aborted(signal))
+            return { state: "rejected" };
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            return { state: "rejected" };
+        handle = await fsOps.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const before = await handle.stat();
+        const pathBefore = await fsOps.lstat(path);
+        if (!sameSafeFile(before, pathBefore) || aborted(signal))
+            throw new Error("unsafe resume file");
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of handle.createReadStream({ autoClose: false })) {
+            if (aborted(signal))
+                throw new Error("cancelled");
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += bytes.length;
+            if (total > MAX_TOML_BYTES)
+                throw new Error("oversized resume file");
+            chunks.push(bytes);
+        }
+        if (aborted(signal))
+            throw new Error("cancelled");
+        const content = Buffer.concat(chunks, total);
+        if (!content.equals(expected))
+            throw new Error("different resume bytes");
+        const fdAfter = await handle.stat();
+        const pathAfter = await fsOps.lstat(path);
+        if (!sameIdentity(before, fdAfter) ||
+            !sameSafeFile(fdAfter, pathAfter) ||
+            aborted(signal))
+            throw new Error("resume path changed");
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await handle.close();
+        handle = undefined;
+        if (aborted(signal))
+            throw new Error("cancelled");
+        await ensureDirectoryTree(runDir, stateRoot, signal, fsOps);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        const finalPath = await fsOps.lstat(path);
+        if (!sameSafeFile(before, finalPath) || aborted(signal))
+            throw new Error("resume path changed");
+        return { state: "stored", path };
+    }
+    catch {
+        if (handle !== undefined) {
+            try {
+                await handle.close();
+            }
+            catch {
+                /* resume never owns the existing file */
+            }
+        }
+        return { state: "rejected" };
+    }
+}
+async function ensureDirectoryTree(directory, stateRoot, signal, fsOps) {
+    const absolute = resolve(directory);
+    const root = parse(absolute).root;
+    const parts = absolute.slice(root.length).split(sep).filter(Boolean);
+    let current = root;
+    for (const part of parts) {
+        if (aborted(signal))
+            throw new Error("cancelled");
+        current = join(current, part);
+        try {
+            await fsOps.mkdir(current, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+        if (aborted(signal))
+            throw new Error("cancelled");
+        const stat = await fsOps.lstat(current);
+        if (aborted(signal))
+            throw new Error("cancelled");
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error("redirected directory");
+        if (isWithin(stateRoot, current) &&
+            ((stat.mode & 0o022) !== 0 ||
+                (process.getuid !== undefined && stat.uid !== process.getuid())))
+            throw new Error("unsafe storage directory");
+    }
+}
+async function verifyCreatedPath(path, identity, fsOps) {
+    const stat = await fsOps.lstat(path);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        stat.nlink !== 1 ||
+        !privateMode(stat.mode) ||
+        !sameIdentity(stat, identity))
+        throw new Error("artifact path changed");
+}
+async function removeCreatedFile(path, identity, fsOps) {
+    try {
+        const stat = await fsOps.lstat(path);
+        if (stat.isFile() && !stat.isSymbolicLink() && sameIdentity(stat, identity))
+            await fsOps.unlink(path);
+    }
+    catch {
+        /* missing or replaced paths are untouched */
+    }
+}
+function sameSafeFile(fd, path) {
+    return (fd.isFile() &&
+        path.isFile() &&
+        !path.isSymbolicLink() &&
+        fd.nlink === 1 &&
+        path.nlink === 1 &&
+        privateMode(fd.mode) &&
+        privateMode(path.mode) &&
+        (process.getuid === undefined || fd.uid === process.getuid()) &&
+        sameIdentity(fd, path));
+}
+function sameIdentity(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function privateMode(mode) {
+    return (mode & 0o077) === 0;
+}
+function isWithin(root, path) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}
+function aborted(signal) {
+    return signal?.aborted === true;
+}
+function isAlreadyExists(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EEXIST");
+}

package/dist/env/onboard-draft.js

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { draftEnvironment } from "./draft.js";
+const TEAM_KEY_RE = /^[A-Z][A-Z0-9]{0,15}$/;
+const DESTINATION = ".catalyst/catalyst.toml";
+/** Compose a value-free first settings draft. This does not validate the full settings schema or write files. */
+export function draftOnboardSettings(root, teamKey, deps = {}) {
+    if (typeof teamKey !== "string" || !TEAM_KEY_RE.test(teamKey)) {
+        return {
+            state: "invalid",
+            errors: [
+                "team key must use uppercase letters and digits and start with a letter",
+            ],
+        };
+    }
+    const destinationPath = join(root, DESTINATION);
+    if ((deps.fileExists ?? existsSync)(destinationPath)) {
+        return { state: "existing", destination: DESTINATION };
+    }
+    const environment = draftEnvironment(root, deps);
+    if (environment.state === "invalid")
+        return environment;
+    return {
+        state: "draft",
+        teamKey,
+        names: environment.names,
+        secretNames: environment.secretNames,
+        setup: environment.setup,
+        verify: environment.verify,
+        sources: environment.sources,
+        toml: `[project]\nlinear_team = ${JSON.stringify(teamKey)}\n\n${environment.toml}`,
+    };
+}

package/dist/env/selected-import-writer.js

@@ -0,0 +1,163 @@
+import { envFileInventory, filterEnvFileNames, parseEnvAssignments, } from "./parse-env.js";
+const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+const SAFE_UNCERTAIN = "selected import outcome uncertain";
+const SAFE_INPUT = "selected import input is invalid";
+function fixedError(message) {
+    return new Error(message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateSelectedAssignments(selectedText, selectedNames) {
+    if (typeof selectedText !== "string" ||
+        !Array.isArray(selectedNames) ||
+        !selectedNames.every((name) => typeof name === "string" && NAME_RE.test(name)) ||
+        new Set(selectedNames).size !== selectedNames.length) {
+        throw fixedError(SAFE_INPUT);
+    }
+    const inventory = envFileInventory(selectedText);
+    if (inventory.duplicateNames.length > 0 ||
+        inventory.names.length !== selectedNames.length ||
+        inventory.names.some((name) => !selectedNames.includes(name))) {
+        throw fixedError(SAFE_INPUT);
+    }
+    const entries = parseEnvAssignments(selectedText);
+    if (entries.length !== selectedNames.length)
+        throw fixedError(SAFE_INPUT);
+    const values = new Map();
+    for (const entry of entries) {
+        if (!NAME_RE.test(entry.name) ||
+            !selectedNames.includes(entry.name) ||
+            values.has(entry.name)) {
+            throw fixedError(SAFE_INPUT);
+        }
+        values.set(entry.name, entry.value);
+    }
+    if (selectedNames.some((name) => !values.has(name)))
+        throw fixedError(SAFE_INPUT);
+    return values;
+}
+function validVariableSuccess(reply, name) {
+    if (!isRecord(reply.body))
+        return false;
+    const envVar = reply.body.envVar;
+    const unresolvedReferences = reply.body.unresolvedReferences;
+    return (isRecord(envVar) &&
+        envVar.name === name &&
+        typeof reply.body.created === "boolean" &&
+        Array.isArray(unresolvedReferences) &&
+        unresolvedReferences.every((entry) => typeof entry === "string"));
+}
+function createVariableWriter(writeVariable) {
+    return async (selectedText, selectedNames) => {
+        const ownedNames = Array.isArray(selectedNames)
+            ? [...selectedNames]
+            : selectedNames;
+        if (Array.isArray(ownedNames) && ownedNames.length === 0)
+            return { written: [], failed: [] };
+        const values = validateSelectedAssignments(selectedText, ownedNames);
+        const written = [];
+        const failed = [];
+        for (const name of ownedNames) {
+            let reply;
+            try {
+                reply = await writeVariable(name, values.get(name));
+            }
+            catch {
+                throw fixedError(SAFE_UNCERTAIN);
+            }
+            try {
+                if (!isRecord(reply) || !Number.isInteger(reply.status)) {
+                    throw fixedError(SAFE_UNCERTAIN);
+                }
+                if (reply.status === 200 || reply.status === 201) {
+                    if (!validVariableSuccess(reply, name))
+                        throw fixedError(SAFE_UNCERTAIN);
+                    written.push(name);
+                }
+                else if ([400, 401, 403, 409, 422].includes(reply.status)) {
+                    failed.push(name);
+                }
+                else {
+                    throw fixedError(SAFE_UNCERTAIN);
+                }
+            }
+            catch {
+                throw fixedError(SAFE_UNCERTAIN);
+            }
+        }
+        return { written, failed };
+    };
+}
+function secretOutcomes(reply, selectedNames) {
+    if (reply.status !== 200 || !isRecord(reply.body))
+        return null;
+    const { created, rotated, errors } = reply.body;
+    if (!Array.isArray(created) ||
+        !Array.isArray(rotated) ||
+        !Array.isArray(errors)) {
+        return null;
+    }
+    const failed = [];
+    for (const error of errors) {
+        if (!isRecord(error) || typeof error.name !== "string")
+            return null;
+        failed.push(error.name);
+    }
+    const written = [...created, ...rotated];
+    const outcomes = [...written, ...failed];
+    if (!outcomes.every((name) => typeof name === "string" && NAME_RE.test(name)) ||
+        outcomes.length !== selectedNames.length ||
+        new Set(outcomes).size !== outcomes.length ||
+        outcomes.some((name) => !selectedNames.includes(name)) ||
+        selectedNames.some((name) => !outcomes.includes(name))) {
+        return null;
+    }
+    return { written, failed };
+}
+function createSecretWriter(importSecrets) {
+    return async (selectedText, selectedNames) => {
+        const ownedNames = Array.isArray(selectedNames)
+            ? [...selectedNames]
+            : selectedNames;
+        if (Array.isArray(ownedNames) && ownedNames.length === 0)
+            return { written: [], failed: [] };
+        validateSelectedAssignments(selectedText, ownedNames);
+        const filtered = filterEnvFileNames(selectedText, new Set(ownedNames));
+        if (filtered.found.length !== ownedNames.length)
+            throw fixedError(SAFE_INPUT);
+        let reply;
+        try {
+            reply = await importSecrets(filtered.text, [...ownedNames]);
+        }
+        catch {
+            throw fixedError(SAFE_UNCERTAIN);
+        }
+        try {
+            if (!isRecord(reply) || !Number.isInteger(reply.status)) {
+                throw fixedError(SAFE_UNCERTAIN);
+            }
+            const outcome = secretOutcomes(reply, ownedNames);
+            if (outcome === null)
+                throw fixedError(SAFE_UNCERTAIN);
+            return outcome;
+        }
+        catch {
+            throw fixedError(SAFE_UNCERTAIN);
+        }
+    };
+}
+/** Adapt the CLI's existing single-variable and batch-secret writers for the value-free Q4 helper. */
+export function createSelectedImportWriter(options) {
+    if (options.kind === "variable") {
+        if (options.writeVariable === undefined)
+            throw fixedError(SAFE_INPUT);
+        return createVariableWriter(options.writeVariable);
+    }
+    if (options.kind === "secret") {
+        if (options.importSecrets === undefined)
+            throw fixedError(SAFE_INPUT);
+        return createSecretWriter(options.importSecrets);
+    }
+    throw fixedError(SAFE_INPUT);
+}

package/dist/env/settings-authority.js

@@ -0,0 +1,205 @@
+import { isRepositoryId } from "../repository-id.js";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { validateFullSettings } from "../../vendor/settings/index.js";
+import { executeSelectedNameImport, planSelectedNameImportFromText, } from "./selected-import.js";
+const proofs = new WeakMap();
+const refused = () => ({
+    state: "rejected",
+    message: "Review the current repository settings before importing values",
+});
+const opaque = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+function snapshotContext(raw) {
+    if (!raw ||
+        !isRepositoryId(raw.repoId) ||
+        ![raw.accountId, raw.personId, raw.teamId].every((id) => typeof id === "string" && opaque.test(id)))
+        return null;
+    if (!["owner", "admin", "member"].includes(raw.role) ||
+        !/^[A-Z][A-Z0-9]{0,15}$/.test(raw.teamKey))
+        return null;
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/.test(raw.repoName) ||
+        !isAbsolute(raw.repoRoot))
+        return null;
+    try {
+        const url = new URL(raw.baseUrl);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== "/")
+            return null;
+        return {
+            accountId: raw.accountId,
+            personId: raw.personId,
+            baseUrl: url.origin,
+            role: raw.role,
+            teamId: raw.teamId,
+            teamKey: raw.teamKey,
+            repoId: raw.repoId,
+            repoName: raw.repoName.toLowerCase(),
+            repoRoot: resolve(raw.repoRoot),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Bounded exact local source: refuse redirected roots/directories/files and read a regular file.
+ * The descriptor belongs to this call and is closed even when reading or cancellation fails. */
+export async function readLocalSettings(repoRoot, signal) {
+    let handle;
+    try {
+        if (signal?.aborted || !isAbsolute(repoRoot))
+            return null;
+        const root = resolve(repoRoot);
+        const directory = join(root, ".catalyst");
+        if ((await realpath(root)) !== root ||
+            (await realpath(directory)) !== directory ||
+            signal?.aborted)
+            return null;
+        const path = join(directory, "catalyst.toml");
+        const expected = await lstat(path);
+        if (!expected.isFile() || expected.size > 1_048_576)
+            return null;
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stat = await handle.stat();
+        if (!stat.isFile() ||
+            stat.dev !== expected.dev ||
+            stat.ino !== expected.ino ||
+            stat.size > 1_048_576 ||
+            signal?.aborted)
+            return null;
+        const bytes = await handle.readFile();
+        if (bytes.length > 1_048_576 || signal?.aborted)
+            return null;
+        const current = await lstat(path);
+        if (current.dev !== stat.dev ||
+            current.ino !== stat.ino ||
+            (await realpath(root)) !== root ||
+            (await realpath(directory)) !== directory ||
+            signal?.aborted)
+            return null;
+        // Invalid UTF-8 must not be normalized into a different reviewed source.
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return text;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+async function readCurrentSource(ports, kind, signal) {
+    if (signal?.aborted)
+        return null;
+    const before = snapshotContext(await ports.readContext(signal));
+    // Both current variable and secret write rails require an administrator or owner.
+    if (!before || !["owner", "admin"].includes(before.role) || signal?.aborted)
+        return null;
+    const text = await ports.readSettings(before.repoRoot, signal);
+    const after = snapshotContext(await ports.readContext(signal));
+    if (text === null ||
+        !after ||
+        signal?.aborted ||
+        JSON.stringify(before) !== JSON.stringify(after))
+        return null;
+    const checked = validateFullSettings(text);
+    if (!checked.ok || checked.linearTeam !== before.teamKey)
+        return null;
+    const sourceBinding = createHash("sha256")
+        .update(JSON.stringify([
+        before,
+        createHash("sha256").update(text).digest("hex"),
+        "90d646c7d2f1e52348625e76aeb504d56042e54e",
+        kind,
+    ]))
+        .digest("hex");
+    return {
+        sourceBinding,
+        names: kind === "secrets" ? checked.secretNames : checked.variableNames,
+    };
+}
+/** Authority reads are read-only. A stalled injected port cannot hold the CLI indefinitely;
+ * late completion observes the owned abort signal and cannot produce an accepted source. */
+async function currentSource(ports, kind, signal) {
+    if (signal?.aborted)
+        return null;
+    const owned = new AbortController();
+    const combined = signal
+        ? AbortSignal.any([signal, owned.signal])
+        : owned.signal;
+    let timer;
+    let remove = () => { };
+    try {
+        return await new Promise((resolve) => {
+            const stopped = () => resolve(null);
+            combined.addEventListener("abort", stopped, { once: true });
+            remove = () => combined.removeEventListener("abort", stopped);
+            timer = setTimeout(() => owned.abort(), 30_000);
+            timer.unref();
+            Promise.resolve()
+                .then(() => readCurrentSource(ports, kind, combined))
+                .then((source) => resolve(combined.aborted ? null : source), () => resolve(null));
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        remove();
+    }
+}
+export async function reviewSettingsImport(input) {
+    try {
+        if (input.kind !== "variables" && input.kind !== "secrets")
+            return refused();
+        const source = await currentSource(input.ports, input.kind, input.signal);
+        if (!source)
+            return refused();
+        const plan = planSelectedNameImportFromText({
+            text: input.text,
+            requestedNames: [...input.requestedNames],
+            allowedNames: source.names,
+        });
+        if (plan.state !== "ready")
+            return refused();
+        const review = Object.freeze({
+            state: "ready",
+            kind: input.kind,
+            selectedNames: Object.freeze([...plan.selectedNames]),
+        });
+        proofs.set(review, {
+            kind: input.kind,
+            sourceBinding: source.sourceBinding,
+            plan,
+        });
+        return review;
+    }
+    catch {
+        return refused();
+    }
+}
+/** Review objects are process-local capabilities. A serialized receipt, reconstructed object or
+ * changed settings/context cannot authorize a write; values remain inside the selected writer. */
+export async function executeReviewedSettingsImport(input) {
+    try {
+        const proof = proofs.get(input.review);
+        if (!proof)
+            return refused();
+        // Claim synchronously, before the first await: concurrent attempts cannot share capability.
+        // A rejected or cancelled execution also requires a new review.
+        proofs.delete(input.review);
+        const source = await currentSource(input.ports, proof.kind, input.signal);
+        if (!source ||
+            source.sourceBinding !== proof.sourceBinding ||
+            input.signal?.aborted)
+            return refused();
+        return await executeSelectedNameImport(input.text, proof.plan, source.names, input.writer);
+    }
+    catch {
+        return refused();
+    }
+}