@catalyst-cloud/cli 0.14.5 → 0.14.7

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,203 @@
+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 ||
+        ![raw.accountId, raw.personId, raw.teamId, raw.repoId].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();
+    }
+}

package/dist/events-cloud-tail.js

@@ -0,0 +1,134 @@
+import { cloudEvents } from "./events-cloud.js";
+/** The same matching rules as the local tail, so a filter means one thing from either source. */
+export function eventMatches(filter) {
+    const ticket = filter.ticket?.toUpperCase();
+    return (event) => (!filter.type || event.type === filter.type) &&
+        (!ticket || payloadReferences(event.payload, ticket));
+}
+function payloadReferences(value, ticket) {
+    if (typeof value === "string")
+        return value.toUpperCase() === ticket;
+    if (Array.isArray(value))
+        return value.some((item) => payloadReferences(item, ticket));
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) && typeof item === "string"
+        ? item.toUpperCase() === ticket
+        : payloadReferences(item, ticket));
+}
+function pipeClosed(error) {
+    const code = error?.code;
+    return code === "EPIPE" || code === "ERR_STREAM_DESTROYED";
+}
+// Resolves once the line has left this process, so a consumer sees it before the next is read.
+function writeLine(out, line, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return resolve();
+        const abort = () => resolve();
+        signal.addEventListener("abort", abort, { once: true });
+        const settle = (error) => {
+            signal.removeEventListener("abort", abort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        try {
+            out.write(line, (error) => settle(error));
+        }
+        catch (error) {
+            settle(error);
+        }
+    });
+}
+/** Print every matching cloud event as one NDJSON line until aborted, matched, or the pipe closes. */
+export async function tailCloudEvents(ctx, options, deps = {}) {
+    const { out } = options;
+    const filter = options.filter ?? {};
+    const filtered = eventMatches(filter);
+    const matches = (event) => filtered(event) && (options.where?.(event) ?? true);
+    const reader = new AbortController();
+    const stop = () => reader.abort(options.signal.reason);
+    if (options.signal.aborted)
+        stop();
+    else
+        options.signal.addEventListener("abort", stop, { once: true });
+    let closed = false;
+    let failure;
+    const broken = (error) => {
+        if (pipeClosed(error))
+            closed = true;
+        else
+            failure ??= error;
+        reader.abort(error);
+    };
+    out.on("error", broken);
+    let cursor = options.after;
+    let written = 0;
+    let matched;
+    // The server narrows what it sends when it can; every event is still matched here.
+    const serverFilter = {
+        ...(filter.type ? { type: filter.type } : {}),
+        ...(filter.ticket ? { ticket: filter.ticket.toUpperCase() } : {}),
+    };
+    try {
+        const events = (deps.events ?? cloudEvents)(ctx, { after: options.after, filter: serverFilter, signal: reader.signal }, deps);
+        for await (const event of events) {
+            if (reader.signal.aborted)
+                break;
+            // A reconnect may replay what was already printed; the sequence is the identity.
+            if (cursor !== undefined && event.sequence <= cursor)
+                continue;
+            if (matches(event)) {
+                await writeLine(out, `${JSON.stringify(event)}\n`, reader.signal);
+                // Aborted mid-write: the line was not confirmed, so it does not move the cursor.
+                if (reader.signal.aborted)
+                    break;
+                written += 1;
+                cursor = event.sequence;
+                if (options.once) {
+                    matched = event;
+                    break;
+                }
+            }
+            else
+                cursor = event.sequence;
+        }
+    }
+    catch (error) {
+        if (pipeClosed(error))
+            closed = true;
+        else if (!reader.signal.aborted)
+            failure ??= error;
+    }
+    finally {
+        options.signal.removeEventListener("abort", stop);
+        reader.abort();
+        // After EPIPE the stream can still emit its error; the listener stays so that cannot crash.
+        if (!closed)
+            out.off("error", broken);
+    }
+    if (failure !== undefined)
+        throw failure;
+    if (matched)
+        return { outcome: "matched", cursor, written, event: matched };
+    if (closed)
+        return { outcome: "closed", cursor, written };
+    return { outcome: options.signal.aborted ? "aborted" : "ended", cursor, written };
+}
+/** Print the first matching cloud event and stop, or report a timeout with nothing printed. */
+export async function waitForCloudEvent(ctx, options, deps = {}) {
+    const timer = new AbortController();
+    const timeout = setTimeout(() => timer.abort(new Error("event wait timed out")), options.timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timer.signal]) : timer.signal;
+    try {
+        const result = await tailCloudEvents(ctx, { after: options.after, filter: options.filter, out: options.out, signal, where: options.predicate, once: true }, deps);
+        if (result.outcome === "aborted" && timer.signal.aborted && !options.signal?.aborted)
+            return { ...result, outcome: "timeout" };
+        return result;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}