promigence 0.1.0-beta.12

package/dist/connectreq.js

@@ -0,0 +1,125 @@
+import { PromigenceError } from "./sdk/index.js";
+import { bool, nexts } from "./commands.js";
+import { emit, okEnvelope, write } from "./io.js";
+import { headless, openBrowser } from "./login.js";
+import { jsonLine } from "./term.js";
+const NAMES = { github: "GitHub", gitlab: "GitLab" };
+const CONNECTED = new Set(["connected", "updated", "already_connected"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function consoleTicket(mint) {
+    try {
+        return await mint();
+    }
+    catch (e) {
+        if (e instanceof PromigenceError && e.code === "not_found")
+            return null;
+        throw e;
+    }
+}
+function endLine(host, r) {
+    const a = r.account ?? `the ${NAMES[host]} account`;
+    switch (r.state) {
+        case "connected":
+            return `connected: ${a}`;
+        case "updated":
+            return `already connected: ${a} (repository access updated)`;
+        case "already_connected":
+            return `already connected: ${a}`;
+        default:
+            return `${r.state}: ${r.message}`;
+    }
+}
+function fixFor(host, r) {
+    const again = `\`promigence ${host} connect\``;
+    const n = NAMES[host];
+    switch (r.state) {
+        case "wrong_user":
+            return `The page was opened in a browser signed in to another Promigence account, so nothing was started. Run ${again} again and open the page where you are signed in to the console as yourself.`;
+        case "declined":
+            return `The connection was declined, so nothing was connected. Run ${again} again to start over.`;
+        case "other_org":
+            return `That ${n} account is connected to another Promigence organization. Disconnect it there first (\`promigence ${host} disconnect\` with that organization's key), then run ${again} again.`;
+        case "needs_admin":
+            return `Connect it signed in to ${n} as an owner (admin) of that account, or ask one of its owners to; then run ${again} again.`;
+        case "not_installer":
+            return `The ${n} user who installed the App on that account can connect it now; an owner of the account can 15 minutes after the install. Then run ${again} again.`;
+        default:
+            return `Run ${again} again. If it fails the same way, write to support@promigence.ai with the time it happened.`;
+    }
+}
+export async function consoleConnect(ctx, host, o) {
+    const n = NAMES[host];
+    const url = o.ticket.connect_url;
+    const opened = bool(ctx, "--no-open") || headless() ? false : openBrowser(url);
+    const noWait = bool(ctx, "--no-wait");
+    if (ctx.mode === "json") {
+        await write(process.stderr, jsonLine(process.stderr, {
+            hint: "connect_url", connect_url: url, request_id: o.ticket.request_id, expires_at: o.ticket.expires_at, opened,
+        }));
+    }
+    else {
+        await write(process.stderr, [
+            opened
+                ? `Opening the Promigence console to connect ${n}…`
+                : `Open this page in a browser where you are signed in to the Promigence console (any device works):`,
+            `  ${opened ? "If it did not open: " : ""}${url}`,
+            host === "github"
+                ? "  It starts the connection on GitHub, where you choose the account, and all repositories or only the ones you pick."
+                : "  It starts the connection on GitLab, where you approve read-only access.",
+            "  The page works once, within 5 minutes, and only signed in to the console as you, an owner of this organization: keep it to yourself.",
+            ...(noWait ? [] : [`  Waiting up to ${o.waitText} (Ctrl-C stops waiting; the connection still finishes in the browser).`]),
+        ].join("\n") + "\n");
+    }
+    if (noWait) {
+        const next = nexts([`promigence ${host} status`, "once it is done: the connection"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+            connect_url: url, request_id: o.ticket.request_id, expires_at: o.ticket.expires_at, opened, waited: false, connected: [],
+        }, next), [`connect page: ${url}`, `  next: ${next[0].cmd}`], 0, ctx.pointer);
+    }
+    const t0 = Date.now();
+    let said = "";
+    for (;;) {
+        await sleep(Math.min(o.pollMs, Math.max(0, o.bound - (Date.now() - t0))));
+        const r = await o.poll();
+        if (r.state !== "pending")
+            return finish(ctx, host, r, { url, opened, waitedMs: Date.now() - t0, ...o });
+        if (r.message !== said && ctx.mode !== "json") {
+            said = r.message;
+            await write(process.stderr, `  ${r.message}\n`);
+        }
+        if (Date.now() - t0 >= o.bound) {
+            throw new PromigenceError({
+                code: "timeout",
+                message: `no ${n} connection finished within ${o.waitText}`,
+                fix: `Finish it in the browser if it is still open, then \`promigence ${host} status\`. Otherwise run \`promigence ${host} connect\` again for a new page (each works once, within 5 minutes).`,
+                exitCode: 11,
+            });
+        }
+    }
+}
+async function finish(ctx, host, r, o) {
+    const n = NAMES[host];
+    if (CONNECTED.has(r.state)) {
+        const connected = await o.connections(r);
+        const next = nexts(...o.okNext);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+            connect_url: o.url, opened: o.opened, waited: true, waited_ms: o.waitedMs, state: r.state, request: r, connected,
+        }, next), [endLine(host, r), `  ${r.message}`, `  next: ${next[0].cmd}`], 0, ctx.pointer);
+    }
+    if (r.state === "pending_provider_approval") {
+        const next = nexts([`promigence ${host} connect`, `once an owner of the account approved it on ${n}`]);
+        const line = `waiting for an owner of ${r.account ?? "that account"} to approve it on ${n}; run \`promigence ${host} connect\` again after`;
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+            connect_url: o.url, opened: o.opened, waited: true, waited_ms: o.waitedMs, state: r.state, request: r, connected: [],
+        }, next), [line, `  ${r.message}`], 0, ctx.pointer);
+    }
+    if (r.state === "expired") {
+        throw new PromigenceError({
+            code: "timeout",
+            message: r.message,
+            fix: `Nothing was connected. Run \`promigence ${host} connect\` again and finish it in the browser: the page works within 5 minutes, the connection within 15.`,
+            exitCode: 11,
+        });
+    }
+    throw new PromigenceError({ code: "not_connected", message: `${r.state}: ${r.message}`, fix: fixFor(host, r), exitCode: 7 });
+}

package/dist/credfile.js

@@ -0,0 +1,188 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DEFAULT_API_URL, PromigenceClient, credentialsPath, storedCredentialsText } from "./sdk/index.js";
+import { encodeCredentials, keychainCacheSet, keychainDelete, keychainRead, keychainStore, keychainWrite, keychainsToClear, storeLabel, } from "./sdk/credstore.js";
+import { recordNotice, usageError } from "./io.js";
+import { sh } from "./term.js";
+function lstatOrUndefined(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+export function secureConfigDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = statSync(dir);
+    if (!st.isDirectory()) {
+        throw usageError(`${dir} is not a directory`, `Move it aside; the CLI keeps its credentials in ${dir}/.`);
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid === undefined)
+        return;
+    if (st.uid !== uid) {
+        throw usageError(`${dir} belongs to another user (uid ${st.uid})`, `Refusing to store an API key there. Remove it or set XDG_CONFIG_HOME to a directory you own.`);
+    }
+    if ((st.mode & 0o077) !== 0)
+        chmodSync(dir, 0o700);
+}
+export function checkCredentialsPath(path) {
+    secureConfigDir(dirname(path));
+    const st = lstatOrUndefined(path);
+    if (st && !st.isFile()) {
+        throw usageError(`${path} is ${st.isSymbolicLink() ? "a symlink" : "not a regular file"}; refusing to write an API key through it`, `Remove it (rm ${path}) and run the command again.`);
+    }
+    return st;
+}
+export function writeCredentialsFile(path, body) {
+    const dir = dirname(path);
+    const st = checkCredentialsPath(path);
+    if (body === undefined) {
+        if (st)
+            unlinkSync(path);
+        return;
+    }
+    const tmp = join(dir, `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0);
+    const fd = openSync(tmp, flags, 0o600);
+    try {
+        writeSync(fd, JSON.stringify(body, null, 2) + "\n");
+        fsyncSync(fd);
+    }
+    catch (e) {
+        closeSync(fd);
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
+    }
+    closeSync(fd);
+    try {
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
+    }
+}
+export const MINTED_BY = "promigence login";
+export function loginMintedKey(env = process.env) {
+    const stored = storedCredentialsText(env);
+    if (stored === undefined)
+        return undefined;
+    try {
+        const j = JSON.parse(stored.text.trim());
+        const [apiKey, keyId, apiUrl] = [j["api_key"], j["key_id"], j["api_url"]];
+        if (j["minted_by"] !== MINTED_BY || typeof apiKey !== "string" || typeof keyId !== "string" || !apiKey || !keyId)
+            return undefined;
+        return { apiKey, keyId, apiUrl: typeof apiUrl === "string" ? apiUrl : undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function storedWhere(r) {
+    return r.store === "file" ? `${r.path} (0600)` : storeLabel(r.store);
+}
+const isCi = (env) => {
+    const v = (env["CI"] ?? "").trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+};
+function message(e) {
+    return e.message ?? String(e);
+}
+function clearFix(store, path) {
+    return store === "macos-keychain"
+        ? `unlock the keychain and run \`promigence logout\` again, or remove it: security delete-generic-password -s promigence-cli -a "${path}"`
+        : `unlock the keyring and run \`promigence logout\` again, or remove it: secret-tool clear service promigence-cli account "${path}"`;
+}
+export function storeCredentials(body, env = process.env) {
+    const path = credentialsPath(env);
+    const chosen = keychainStore(env);
+    const warnings = [];
+    const left = [];
+    const clearOthers = (except) => {
+        for (const k of keychainsToClear(env)) {
+            if (k === except)
+                continue;
+            const d = keychainDelete(k, path, env);
+            if (d.ok) {
+                keychainCacheSet(k, path, undefined);
+            }
+            else {
+                left.push(k);
+                warnings.push(`a sign-in in ${storeLabel(k)} could not be removed (${d.reason}); ${clearFix(k, path)}`);
+            }
+        }
+    };
+    if (body === undefined || !body["api_key"]) {
+        writeCredentialsFile(path, body !== undefined && Object.keys(body).length > 0 ? body : undefined);
+        clearOthers();
+        return { store: "file", path, warnings, left };
+    }
+    let reason;
+    if (chosen !== undefined) {
+        const text = encodeCredentials(body);
+        const w = keychainWrite(chosen, path, text, env);
+        if (w.ok) {
+            const back = keychainRead(chosen, path, env);
+            if (back.status === "found" && back.text === text) {
+                keychainCacheSet(chosen, path, text);
+                try {
+                    writeCredentialsFile(path, undefined);
+                }
+                catch (e) {
+                    try {
+                        writeCredentialsFile(path, body);
+                    }
+                    catch { }
+                    warnings.push(`the credentials file ${path} could not be removed (${message(e)}); it holds the same key as ${storeLabel(chosen)}. Remove it: rm ${path}`);
+                }
+                clearOthers(chosen);
+                return { store: chosen, path, warnings, left };
+            }
+            keychainDelete(chosen, path, env);
+            keychainCacheSet(chosen, path, undefined);
+            reason = back.status === "found" ? "it gave back something else" : back.status === "absent" ? "it did not keep the item" : back.reason;
+        }
+        else {
+            reason = w.reason;
+        }
+    }
+    writeCredentialsFile(path, body);
+    clearOthers();
+    let note;
+    if (chosen !== undefined)
+        note = `${storeLabel(chosen)} could not take the key (${reason}), so it is in ${path} (0600)`;
+    else if ((env["PROMIGENCE_CREDENTIAL_STORE"] ?? "").trim().toLowerCase() !== "file" && process.stderr.isTTY && !isCi(env)) {
+        note = `no OS keychain is available here, so the key is in ${path} (0600)`;
+    }
+    return note === undefined ? { store: "file", path, warnings, left } : { store: "file", path, note, warnings, left };
+}
+export async function revokeReplacedKey(previous, why, replacement) {
+    try {
+        await new PromigenceClient({ apiKey: previous.apiKey, apiUrl: previous.apiUrl ?? DEFAULT_API_URL, onNotice: recordNotice })
+            .request({
+            method: "DELETE", path: `/keys/${encodeURIComponent(previous.keyId)}?reason=replaced`,
+            ...(replacement ? { headers: { "promigence-replaced-by": replacement } } : {}),
+        });
+        return { revoked: previous.keyId };
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "auth")
+            return {};
+        return {
+            warning: `the key ${why} (${previous.keyId}) was not revoked (${err.code ?? "error"}: ${err.message}); revoke it with \`${sh `promigence keys revoke ${previous.keyId}`}\``,
+        };
+    }
+}

package/dist/credits.js

@@ -0,0 +1,197 @@
+import { createInterface } from "node:readline";
+import { PromigenceClient } from "./sdk/index.js";
+import { bool, clientOpts, nexts } from "./commands.js";
+import { deviceFetch, deviceHeader } from "./device.js";
+import { emit, okEnvelope, recordNotice, write } from "./io.js";
+import { headless, openBrowser } from "./login.js";
+import { usd } from "./money.js";
+export function dollars(n) {
+    if (typeof n !== "number" || !Number.isFinite(n))
+        return "free credit";
+    return Number.isInteger(n) ? `$${n}` : usd(n);
+}
+export function campaignName(c) {
+    if (!c)
+        return undefined;
+    if (typeof c === "string")
+        return c;
+    return typeof c.name === "string" ? c.name : typeof c.campaign_id === "string" ? c.campaign_id : undefined;
+}
+export function stateWords(o) {
+    switch (o.state) {
+        case "claimable": return `${dollars(o.credit_usd)} of free credit is waiting for you to claim it`;
+        case "claimed": return "your free credit is claimed";
+        case "pending_review": return "we are checking your free credit (the claim page says what releases it)";
+        case "needs_card": return "free credit for this account comes with a card on file";
+        case "not_eligible": return "this account is not eligible for the free credit";
+        case "offer_ended": return "the free-credit offer has ended";
+        case "none": return "there is no free-credit offer for this account";
+        default: return `free credit: ${o.state}`;
+    }
+}
+const say = (o) => (typeof o.message === "string" && o.message.trim() ? o.message.trim() : stateWords(o));
+function offerNext(o) {
+    switch (o.state) {
+        case "claimable": return nexts(["promigence credits claim", "open the claim page and accept the terms"]);
+        case "needs_card": return nexts(["promigence billing card", "add a card; the card bonus comes with it"]);
+        case "pending_review": return nexts(["promigence credits", "check again later"]);
+        default: return nexts(["promigence me", "your org, limits and credit"]);
+    }
+}
+export function getOffer(c) {
+    return c.request({ method: "GET", path: "/credits/offer" });
+}
+export function getClaimLink(c) {
+    return c.request({ method: "POST", path: "/credits/claim-link", body: {} });
+}
+export function claimClient(opts) {
+    const f = deviceFetch(deviceHeader());
+    return new PromigenceClient({ ...opts, ...(f ? { fetch: f } : {}) });
+}
+function claimLines(o, link, opened) {
+    const credit = dollars(o.credit_usd);
+    return [
+        opened
+            ? `You have ${credit} of free credit waiting. Opening the claim page…`
+            : `You have ${credit} of free credit waiting. Open the claim page to accept the terms and claim it:`,
+        `  ${opened ? "If it did not open: " : ""}${link.url}`,
+        `  The link works once${link.expires_at ? `, until ${link.expires_at}` : ", for 15 minutes"}; for a new one: promigence credits claim`,
+    ];
+}
+function maybeOpen(ctx, url) {
+    if (bool(ctx, "--no-open") || bool(ctx, "--no-browser") || headless())
+        return false;
+    return openBrowser(url);
+}
+export async function offerAfterLogin(ctx, apiUrl, apiKey, consoleHome) {
+    const opts = { apiKey, apiUrl, onNotice: recordNotice, requestTimeoutMs: 10_000, maxRetries: 1 };
+    let offer;
+    try {
+        offer = await getOffer(new PromigenceClient(opts));
+    }
+    catch (e) {
+        const err = e;
+        if (err?.code === "not_found")
+            return { field: null, lines: [] };
+        return { field: null, lines: ["  free credit: could not check just now; see `promigence credits`"] };
+    }
+    if (!offer || typeof offer.state !== "string")
+        return { field: null, lines: [] };
+    if (offer.state === "none")
+        return { field: { ...offer }, lines: [] };
+    if (offer.state !== "claimable")
+        return { field: { ...offer }, lines: [`  free credit: ${say(offer)}`] };
+    if (consoleHome) {
+        return {
+            field: { ...offer, claim_url: consoleHome, opened: false },
+            lines: [`  free credit: ${dollars(offer.credit_usd)} is waiting; claim it in the console: ${consoleHome}`],
+        };
+    }
+    let link;
+    try {
+        link = await getClaimLink(claimClient(opts));
+        if (!link || typeof link.url !== "string")
+            throw new Error("no url");
+    }
+    catch {
+        return {
+            field: { ...offer },
+            lines: [`  free credit: ${dollars(offer.credit_usd)} is waiting; claim it with \`promigence credits claim\``],
+        };
+    }
+    const opened = maybeOpen(ctx, link.url);
+    return {
+        field: { ...offer, claim_url: link.url, claim_expires_at: link.expires_at ?? null, opened },
+        lines: claimLines(offer, link, opened),
+    };
+}
+async function askLine(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await new Promise((resolve) => rl.question(prompt, resolve));
+    }
+    finally {
+        rl.close();
+    }
+}
+export function canAsk(env = process.env) {
+    const ci = (env["CI"] ?? "").trim().toLowerCase();
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && (ci === "" || ci === "0" || ci === "false");
+}
+export async function claimOnRefusal(ctx, io = {}) {
+    const opts = { ...clientOpts(ctx), onNotice: recordNotice };
+    let o;
+    try {
+        o = await getOffer(new PromigenceClient(opts));
+    }
+    catch {
+        return undefined;
+    }
+    if (!o || o.state !== "claimable")
+        return undefined;
+    const credit = typeof o.credit_usd === "number" ? `${dollars(o.credit_usd)} of free credit` : "free credit";
+    await write(process.stderr, `This account has ${credit} waiting to be claimed; nothing was started or charged.\n`);
+    const answer = await (io.ask ?? askLine)("Claim it now? It opens the claim page in your browser, where you accept the terms. [y/N] ");
+    if (!/^\s*y(es)?\s*$/i.test(answer))
+        return ["Not claimed. When you are ready: promigence credits claim"];
+    let link;
+    try {
+        link = await getClaimLink(claimClient(opts));
+        if (!link || typeof link.url !== "string")
+            throw new Error("no claim link in the answer");
+    }
+    catch (e) {
+        const err = e;
+        return [
+            `Could not open the claim page: ${err?.message ?? String(e)}`,
+            `  Try again: promigence credits claim${err?.code === "forbidden" ? " (owners; members ask an owner)" : ""}`,
+        ];
+    }
+    const opened = maybeOpen(ctx, link.url);
+    return [...claimLines(o, link, opened), "Once it is claimed, run the command again."];
+}
+async function cardState(c, o) {
+    const none = { off: false, onFile: false };
+    if (!(typeof o.card_bonus_usd === "number" && o.card_bonus_usd > 0) || o.state === "none")
+        return none;
+    return c.billing.usage().then((b) => ({ off: b.billing_enabled === false, onFile: b.card_on_file === true })).catch(() => none);
+}
+function offerLines(head, o, st = { off: false, onFile: false }) {
+    const lines = [`${head}: ${say(o)}`];
+    if (o.state !== "none") {
+        if (typeof o.credit_usd === "number")
+            lines.push(`  credit: ${dollars(o.credit_usd)}`);
+        if (typeof o.card_bonus_usd === "number" && o.card_bonus_usd > 0) {
+            lines.push(st.onFile
+                ? `  card bonus: ${dollars(o.card_bonus_usd)} more with your first paid invoice`
+                : `  card bonus: ${dollars(o.card_bonus_usd)} more when you add a card${st.off ? " (card payments are not open yet)" : " (promigence billing card)"}`);
+        }
+        if (o.expires_at)
+            lines.push(`  expires: ${o.expires_at}`);
+        const camp = campaignName(o.campaign);
+        if (camp)
+            lines.push(`  campaign: ${camp}`);
+    }
+    return lines;
+}
+const credits = async (ctx) => {
+    const c = new PromigenceClient({ ...clientOpts(ctx), onNotice: recordNotice });
+    const o = await getOffer(c);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...o }, offerNext(o)), offerLines("promigence credits", o, await cardState(c, o)), 0, ctx.pointer);
+};
+const creditsClaim = async (ctx) => {
+    const opts = { ...clientOpts(ctx), onNotice: recordNotice };
+    const c = new PromigenceClient(opts);
+    const o = await getOffer(c);
+    if (o.state !== "claimable") {
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...o, claim_url: null }, offerNext(o)), offerLines("promigence credits claim", o, await cardState(c, o)), 0, ctx.pointer);
+    }
+    const link = await getClaimLink(claimClient(opts));
+    const opened = maybeOpen(ctx, link.url);
+    const next = nexts(["promigence credits", "after the claim page: the credit and its expiry"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...o, claim_url: link.url, claim_expires_at: link.expires_at ?? null, opened }, next), claimLines(o, link, opened), 0, ctx.pointer);
+};
+export const CREDITS_HANDLERS = {
+    credits,
+    "credits claim": creditsClaim,
+};

package/dist/devcontainer.d.ts

@@ -0,0 +1,99 @@
+import { type TierEntry } from "./generated.js";
+export declare const DEVCONTAINER_SPEC = "containers.dev json_reference + features, read 2026-09-18";
+export declare const DEVCONTAINER_NAMES: readonly [".devcontainer/devcontainer.json", ".devcontainer.json"];
+export declare class DevcontainerError extends Error {
+    readonly kind: string;
+    readonly fix: string;
+    readonly file: string | undefined;
+    constructor(kind: string, message: string, fix: string, file?: string);
+}
+export interface JsoncPosition {
+    line: number;
+    column: number;
+}
+export declare function parseJsonc(text: string, file?: string): unknown;
+export declare function discover(root: string): string[];
+export declare function resolveGiven(pathArg: string): string;
+export declare function detectOne(root: string, asked?: boolean): string | undefined;
+export declare function workspaceRootFor(file: string): string;
+export interface LoadedDevcontainer {
+    path: string;
+    dir: string;
+    config: Record<string, unknown>;
+}
+export declare function load(file: string): LoadedDevcontainer;
+export interface SubstitutionContext {
+    localWorkspaceFolder: string;
+    localWorkspaceFolderBasename: string;
+    containerWorkspaceFolder: string;
+    containerWorkspaceFolderBasename: string;
+    localEnv: Readonly<Record<string, string | undefined>>;
+    containerEnv: Readonly<Record<string, string>>;
+    devcontainerId: string;
+    allowContainerEnv: boolean;
+    property: string;
+    file?: string | undefined;
+}
+export declare function substituteString(input: string, ctx: SubstitutionContext): string;
+export declare function substituteDeep<T>(value: T, ctx: SubstitutionContext): T;
+export declare function devcontainerId(workspaceRoot: string, file: string): string;
+export type PlanSource = {
+    kind: "image";
+    image: string;
+} | {
+    kind: "dockerfile";
+    dockerfile: string;
+    context: string;
+};
+export interface LifecycleStep {
+    field: string;
+    command: string;
+    label?: string;
+}
+export interface IgnoredProperty {
+    field: string;
+    why: string;
+}
+export interface Plan {
+    spec: typeof DEVCONTAINER_SPEC;
+    file: string;
+    name: string | undefined;
+    source: PlanSource;
+    env: Record<string, string>;
+    workspaceFolder: string;
+    user: string | undefined;
+    remoteUser?: string | undefined;
+    lifecycle: LifecycleStep[];
+    ports: number[];
+    tier: string | undefined;
+    tierReason: string | undefined;
+    ignored: IgnoredProperty[];
+    notes: string[];
+    localEnvBaked?: string[];
+}
+export interface TranslateOptions {
+    workspaceRoot: string;
+    localEnv?: Readonly<Record<string, string | undefined>>;
+    tiers?: readonly TierEntry[];
+    imageOverride?: string | undefined;
+    allowLocalEnv?: boolean;
+}
+export declare function translate(loaded: LoadedDevcontainer, opts: TranslateOptions): Plan;
+export declare const OPT_IN_TIERS: ReadonlySet<string>;
+export declare function sizeGib(v: unknown, field: string, file: string): number;
+export declare function lifecycleSteps(v: unknown, field: string, ctx: SubstitutionContext, file: string): LifecycleStep[];
+export declare function shellQuote(s: string): string;
+export declare function wrapCommand(plan: Plan, command: string): string;
+export declare function snapshotEnv(plan: Plan): Record<string, string> | undefined;
+export declare function snapshotUsers(plan: Plan): {
+    user: string;
+    setupUser: string;
+} | undefined;
+export interface SetupOptions {
+    repo?: string | undefined;
+    commit?: string | undefined;
+    userSetup?: readonly string[];
+}
+export declare function planSetup(plan: Plan, opts?: SetupOptions): string[];
+export declare function planJson(plan: Plan, setup: readonly string[]): Record<string, unknown>;
+export declare function planLines(plan: Plan, setup: readonly string[]): string[];