@catalyst-cloud/cli 0.13.0 → 0.14.0

package/dist/cli.js

@@ -1,4 +1,4 @@
-// cli.ts — the `catalyst-skills` dispatcher (npm: @catalyst-cloud/catalyst-skills). Verbs live in
+// cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
 import { existsSync } from "node:fs";
 import { parseArgs, positionals, verbHelp } from "./args.js";
@@ -8,14 +8,14 @@ import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
 import { bearerFor, deviceFlowLogin } from "./oauth.js";
 import { openBrowser as defaultOpenBrowser } from "./browser.js";
-import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning } from "./execution.js";
+import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning, } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
 import { cmdRuntime } from "./runtime-verb.js";
 import { cmdEvents } from "./events.js";
 import { stdinIsTty } from "./prompt.js";
-import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion } from "./skill-shape.js";
+import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion, } from "./skill-shape.js";
 import { installedBundleVersion, installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine, } from "./skills.js";
 import { cmdWatch } from "./watch.js";
 import { cmdWrite } from "./write.js";
@@ -25,18 +25,20 @@ import { cmdRelease } from "./release.js";
 import { cmdEnvironment } from "./environment.js";
 import { cmdEnv } from "./env.js";
 import { cmdSecret } from "./secret.js";
+import { cmdVar } from "./var.js";
 import { cmdTeam } from "./team.js";
 import { cmdCapabilities } from "./capabilities.js";
+import { cmdProject } from "./project.js";
+import { cmdRepo } from "./repo.js";
+import { cmdLegacy, findLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdConnections } from "./connections.js";
+import { cmdOnboard } from "./onboard.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
     "catalyst-github",
     "catalyst-linear",
     "catalyst-onboard",
-    "catalyst-setup",
-    "connect-me",
-    "how-catalyst-works",
     "run-this-project",
     "unstick",
     "what-needs-me",
@@ -57,11 +59,12 @@ export function usageText() {
         "  catalyst login --key <personal-key> [--base-url <url>]   (or CATALYST_CLOUD_TOKEN, for a key)",
         "  catalyst join ...   (deprecated alias of login; removed in the next minor version)",
         "  catalyst install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
+        "  catalyst onboard [--resume-from <step>] [--only <step>] [--yes] [--dry-run] [--json]",
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst mcp add|list|remove (vault references only)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
-        "  catalyst replica <start [--detach]|stop|status [--probe]|sql \"<select>\"|schema [table]>",
+        '  catalyst replica <start [--detach]|stop|status [--probe]|sql "<select>"|schema [table]>',
         "  catalyst runtime <status [--json]|install|path|uninstall>   (a pinned Node this CLI manages itself)",
         "  catalyst events <tail|wait-for|query|status [--probe]> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
         "  catalyst explain <ticket> | history <ticket> | running [--ticket T --phase P] | queue [--team K]",
@@ -70,10 +73,15 @@ export function usageText() {
         "  catalyst ask <raise|accept|list> ...",
         "  catalyst release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
         "  catalyst environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve   (your account; needs login)",
-        "  catalyst env <inventory [path] | check <file>>   (this repository, offline — no login, no network)",
-        "  catalyst secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name>",
+        "  catalyst env <inventory [path] | check <file> | migrate [catalyst.env.json] | draft [--root DIR] [--diff] [--write]> [--json]   (this repository, offline — no login, no network)",
+        "  catalyst secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name> [--names NAME[,NAME...]]",
+        "  catalyst var set <NAME> | var import <file> [--repo <owner/name>] [--names NAME[,NAME...]]   (plain environment variables)",
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",
         "  catalyst capabilities [--json]   (what this CLI can do, the role each verb needs, and whether this cloud serves it)",
+        "  catalyst project list [--json]   (all tenant projects, including those with no stage mapping)",
+        "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
+        "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
+        "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
         "  catalyst connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
         "",
@@ -111,7 +119,10 @@ function migrateLegacyCliPath(ctx) {
     // An upgrade from @catalyst-cloud/catalyst-skills to @catalyst-cloud/cli removes the old package
     // folder, so the recorded launcher no longer exists and has no sibling. Point it at the launcher
     // that is running now, so `ready` and every skill script work without another login.
-    if (next === null && typeof cfg.cliPath === "string" && cfg.cliPath !== "" && !existsSync(cfg.cliPath)) {
+    if (next === null &&
+        typeof cfg.cliPath === "string" &&
+        cfg.cliPath !== "" &&
+        !existsSync(cfg.cliPath)) {
         next = cliPath();
     }
     if (next === null || next === cfg.cliPath)
@@ -168,6 +179,8 @@ function maybePrintUpdateNotice(args, ctx) {
     }
     if (refreshed.installed.length > 0)
         say(`[catalyst] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
+    if (refreshed.removed.length > 0)
+        say(`[catalyst] removed retired skills ${refreshed.removed.join(", ")} from ${skillsDir}; their work moved into the skills this bundle ships`);
     for (const s of refreshed.skipped) {
         say(`[catalyst] left "${s.name}" alone: ${skillsDir}/${s.name} was not installed by this package (catalyst install --force to replace)`);
     }
@@ -208,6 +221,36 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdLogin(args, ctx, deps);
             case "install":
                 return cmdInstall(args, ctx);
+            case "onboard":
+                return await cmdOnboard(args, ctx, {
+                    runStep: async (id, stepCtx) => {
+                        if (id !== "legacy")
+                            return { state: "skipped" };
+                        const before = findLegacy(stepCtx.home, process.platform).filter((item) => !item.data).length;
+                        const safeCtx = args.json
+                            ? { ...stepCtx, stdout: stepCtx.stderr }
+                            : stepCtx;
+                        const legacyArgs = {
+                            ...args,
+                            command: "legacy",
+                            subcommand: null,
+                            rest: [],
+                            flags: { remove: true, yes: true },
+                            json: false,
+                            help: false,
+                            version: false,
+                        };
+                        const code = await cmdLegacy(legacyArgs, safeCtx, deps.legacy ?? {});
+                        if (code !== 0)
+                            throw new CliError("legacy cleanup did not finish", "onboard-legacy-failed", 10);
+                        const after = findLegacy(stepCtx.home, process.platform).filter((item) => !item.data).length;
+                        return {
+                            state: after === 0 ? "done" : "skipped",
+                            evidence: { found: before, remaining: after },
+                        };
+                    },
+                    isTty: deps.isTty ?? stdinIsTty,
+                }, readManifest().version);
             case "notice":
                 return 0;
             case "status":
@@ -217,7 +260,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "contract":
                 return await cmdContract(args, ctx);
             case "query":
-                return await cmdQuery(args, ctx, { engineDeps: deps.replica?.engineDeps });
+                return await cmdQuery(args, ctx, {
+                    engineDeps: deps.replica?.engineDeps,
+                });
             case "replica":
                 return await cmdReplica(args, ctx, deps.replica);
             case "runtime":
@@ -239,7 +284,11 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "ask":
                 return await cmdAsk(args, ctx);
             case "ready":
-                return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk, offline: args.flags.offline === true });
+                return await cmdReady(args, ctx, {
+                    skillNames: CUSTOMER_SKILLS,
+                    loadSdk: deps.loadSdk,
+                    offline: args.flags.offline === true,
+                });
             case "mcp":
                 return await cmdMcp(args, ctx);
             case "accounts":
@@ -252,10 +301,18 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdEnv(args, ctx, deps.env ?? {});
             case "secret":
                 return await cmdSecret(args, ctx, deps.secret ?? {});
+            case "var":
+                return await cmdVar(args, ctx, deps.var ?? {});
             case "team":
                 return await cmdTeam(args, ctx, deps.team);
             case "capabilities":
                 return await cmdCapabilities(args, ctx);
+            case "project":
+                return await cmdProject(args, ctx);
+            case "repo":
+                return await cmdRepo(args, ctx);
+            case "legacy":
+                return await cmdLegacy(args, ctx, deps.legacy ?? {});
             case "identity":
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
             case "connections":
@@ -269,7 +326,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
     catch (err) {
         if (err instanceof UsageError) {
             ctx.stderr(err.message);
-            ctx.stderr(args.command && args.command in VERB_HELP_KNOWN ? verbHelp(args.command) : usageText());
+            ctx.stderr(args.command && args.command in VERB_HELP_KNOWN
+                ? verbHelp(args.command)
+                : usageText());
             return 1;
         }
         if (err instanceof CliError) {
@@ -283,7 +342,40 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         throw err;
     }
 }
-const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret", "env", "environment", "connections", "identity", "mcp", "team", "capabilities"].map((v) => [v, true]));
+const VERB_HELP_KNOWN = Object.fromEntries([
+    "login",
+    "join",
+    "install",
+    "status",
+    "notice",
+    "me",
+    "contract",
+    "query",
+    "replica",
+    "runtime",
+    "events",
+    "explain",
+    "running",
+    "queue",
+    "watch",
+    "write",
+    "ask",
+    "ready",
+    "accounts",
+    "release",
+    "secret",
+    "env",
+    "environment",
+    "connections",
+    "identity",
+    "mcp",
+    "team",
+    "capabilities",
+    "project",
+    "repo",
+    "legacy",
+    "onboard",
+].map((v) => [v, true]));
 async function cmdLogin(args, ctx, deps) {
     const manifest = readManifest();
     const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
@@ -327,19 +419,24 @@ async function cmdLogin(args, ctx, deps) {
     const written = writeConfig(ctx.home, config);
     ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
     if (me.user) {
-        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId ? "" : " — your Linear identity is not matched yet, so \"what needs me\" will show everyone's asks until an admin matches it in Settings"}`);
+        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId
+            ? ""
+            : ' — your Linear identity is not matched yet, so "what needs me" will show everyone\'s asks until an admin matches it in Settings'}`);
     }
     else {
         ctx.stderr(`[catalyst] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
     }
-    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
+    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE
+        ? ""
+        : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
         const loaded = await loadContract(ctx, config, { refresh: true });
         ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
     }
     catch (err) {
-        if (err instanceof CliError && (err.code === "contract-forbidden" || err.code === "contract-version")) {
+        if (err instanceof CliError &&
+            (err.code === "contract-forbidden" || err.code === "contract-version")) {
             ctx.stderr(`[catalyst] ${err.message}`);
         }
         else {
@@ -376,6 +473,8 @@ function cmdInstall(args, ctx) {
     for (const s of result.skipped) {
         ctx.stdout(`Skipped "${s.name}": ${skillsDir}/${s.name} exists and was not installed by this package (use --force to replace)`);
     }
+    if (result.removed.length > 0)
+        ctx.stdout(`Removed retired skills from ${skillsDir}: ${result.removed.join(", ")}`);
     return 0;
 }
 function cmdStatus(ctx) {
@@ -387,8 +486,12 @@ function cmdStatus(ctx) {
     }
     ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
     ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
-    ctx.stdout(cfg.user ? `As: ${cfg.user.label} (${cfg.user.role})` : "As: the tenant's account key (a host credential — no person)");
-    ctx.stdout(cfg.auth ? `Credential: your login (expires ${relativeExpiry(cfg.auth.expiresAt, ctx.now())})` : "Credential: personal key");
+    ctx.stdout(cfg.user
+        ? `As: ${cfg.user.label} (${cfg.user.role})`
+        : "As: the tenant's account key (a host credential — no person)");
+    ctx.stdout(cfg.auth
+        ? `Credential: your login (expires ${relativeExpiry(cfg.auth.expiresAt, ctx.now())})`
+        : "Credential: personal key");
     ctx.stdout(`Bundle: ${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
     if (cfg.cliPath)
         ctx.stdout(`CLI: ${cfg.cliPath}${existsSync(cfg.cliPath) ? "" : " (missing — re-run login)"}`);
@@ -433,6 +536,8 @@ async function cmdContract(args, ctx) {
     const value = path ? pickPath(loaded.doc, path) : loaded.doc;
     if (path && value === undefined)
         throw new CliError(`the contract has nothing at "${path}"`, "contract-path");
-    ctx.stdout(typeof value === "string" ? value : JSON.stringify(value, null, args.json ? 0 : 2));
+    ctx.stdout(typeof value === "string"
+        ? value
+        : JSON.stringify(value, null, args.json ? 0 : 2));
     return 0;
 }

package/dist/config.js

@@ -111,7 +111,9 @@ export function modernCliPath(recorded) {
     return existsSync(sibling) ? sibling : null;
 }
 export function normalizeBaseUrl(url) {
-    return url.replace(/\/+$/, "");
+    while (url.endsWith("/"))
+        url = url.slice(0, -1);
+    return url;
 }
 /** The origin WITH the versioned prefix — what the SDK and every API read/write take. */
 export function apiBase(cfg) {

package/dist/env/draft.js

@@ -0,0 +1,134 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { convertLegacyEnvironmentJson } from "./legacy.js";
+import { inventoryRepo } from "./inventory.js";
+import { walkRepo } from "./walk.js";
+const SECRET_NAME_RE = /(?:^|_)(?:API_?KEY|AUTH|CREDENTIALS?|PASSWORD|PRIVATE_?KEY|SECRET|TOKEN)(?:_|$)/i;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_VARIABLES = 128;
+/** Build a stable, value-free environment table from repository evidence. `.env` is never read:
+ *  inventoryRepo's walker only opens supported examples and source/config files. The legacy
+ *  declaration is parsed for names and explicit secret flags, and no legacy value escapes. */
+export function draftEnvironment(root, deps = {}) {
+    const inventory = inventoryRepo(root, deps);
+    const files = (deps.listFiles ?? walkRepo)(root);
+    const names = new Set();
+    const secrets = new Set();
+    const sources = new Set();
+    for (const entry of inventory.entries) {
+        if (entry.group === "bindings" || !entry.needsDeclaration || !ENV_NAME_RE.test(entry.name))
+            continue;
+        names.add(entry.name);
+        if (SECRET_NAME_RE.test(entry.name))
+            secrets.add(entry.name);
+        for (const finding of entry.found)
+            sources.add(finding.file);
+    }
+    const legacyPath = join(root, "catalyst.env.json");
+    const legacy = deps.readFile !== undefined ? deps.readFile(legacyPath) : readOptional(legacyPath);
+    if (legacy !== undefined) {
+        const converted = convertLegacyEnvironmentJson(legacy);
+        if (converted.state === "invalid")
+            return converted;
+        for (const name of converted.variableNames)
+            names.add(name);
+        for (const name of converted.secretNames)
+            secrets.add(name);
+        if (converted.variableNames.length > 0)
+            sources.add("catalyst.env.json");
+    }
+    const sortedNames = [...names].sort((a, b) => a.localeCompare(b, "en"));
+    if (sortedNames.length > MAX_VARIABLES) {
+        return { state: "invalid", errors: [`environment has more than ${MAX_VARIABLES} names`] };
+    }
+    const secretNames = [...secrets].filter((name) => names.has(name)).sort((a, b) => a.localeCompare(b, "en"));
+    const standard = standardSteps(root, files, deps);
+    if (standard.error !== undefined)
+        return { state: "invalid", errors: [standard.error] };
+    for (const source of standard.sources)
+        sources.add(source);
+    for (const path of files)
+        if (path.startsWith(".github/workflows/"))
+            sources.add(path);
+    const chunks = ["[environment]"];
+    for (const name of sortedNames)
+        chunks.push([
+            "[[environment.variables]]",
+            `name = ${JSON.stringify(name)}`,
+            ...(secrets.has(name) ? ["secret = true"] : []),
+            "required = false",
+            "",
+        ].join("\n"));
+    chunks.push(...standard.setup, ...standard.verify);
+    const toml = `${chunks.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+    return {
+        state: "valid",
+        names: sortedNames,
+        secretNames,
+        setup: standard.setup,
+        verify: standard.verify,
+        toml,
+        sources: [...sources].sort((a, b) => a.localeCompare(b, "en")),
+    };
+}
+/** Conservative package.json/lockfile inference. No repository script is executed. */
+function standardSteps(root, files, deps) {
+    if (!files.includes("package.json"))
+        return { setup: [], verify: [], sources: [] };
+    const raw = deps.readFile !== undefined ? deps.readFile(join(root, "package.json")) : readOptional(join(root, "package.json"));
+    if (raw === undefined)
+        return { setup: [], verify: [], sources: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { setup: [], verify: [], sources: [], error: "package.json is not valid JSON; refusing to guess setup commands" };
+    }
+    if (!isRecord(parsed))
+        return { setup: [], verify: [], sources: [], error: "package.json must contain a JSON object; refusing to guess setup commands" };
+    const scripts = isRecord(parsed.scripts) ? parsed.scripts : {};
+    const lock = ["bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "package-lock.json"].find((name) => files.includes(name));
+    const manager = lock?.startsWith("bun.") ? "bun"
+        : lock === "pnpm-lock.yaml" ? "pnpm"
+            : lock === "yarn.lock" ? "yarn"
+                : lock === "package-lock.json" ? "npm" : undefined;
+    const setup = [];
+    const verify = [];
+    const sources = ["package.json"];
+    if (manager !== undefined && lock !== undefined) {
+        const install = manager === "npm" ? ["npm", "ci"]
+            : manager === "yarn" ? ["yarn", "install", "--immutable"]
+                : [manager, "install", "--frozen-lockfile"];
+        setup.push(stepToml("setup", "install-dependencies", install, [lock]));
+        sources.push(lock);
+    }
+    const selected = typeof scripts["check"] === "string"
+        ? ["check"]
+        : ["typecheck", "test"].filter((name) => typeof scripts[name] === "string");
+    if (manager !== undefined) {
+        for (const name of selected)
+            verify.push(stepToml("verify", name, [manager, "run", name]));
+    }
+    return { setup, verify, sources };
+}
+function stepToml(section, name, run, cacheKeyFiles = []) {
+    return [
+        `[[environment.${section}]]`,
+        `name = ${JSON.stringify(name)}`,
+        `run = [${run.map((arg) => JSON.stringify(arg)).join(", ")}]`,
+        ...(cacheKeyFiles.length ? [`cache_key_files = [${cacheKeyFiles.map((path) => JSON.stringify(path)).join(", ")}]`] : []),
+        "",
+    ].join("\n");
+}
+function readOptional(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/env/legacy.js

@@ -0,0 +1,54 @@
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SECRET_NAME_RE = /(?:^|_)(?:API_?KEY|AUTH|CREDENTIALS?|PASSWORD|PRIVATE_?KEY|SECRET|TOKEN)(?:_|$)/i;
+/** Convert legacy catalyst.env.json names only. Values and provenance are never copied. */
+export function convertLegacyEnvironmentJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { state: "invalid", errors: ["legacy declaration is not valid JSON"] };
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.environment)) {
+        return {
+            state: "invalid",
+            errors: ["legacy declaration must contain an environment array"],
+        };
+    }
+    const errors = [];
+    const names = new Set();
+    const secretNames = [];
+    for (const [index, entry] of parsed.environment.entries()) {
+        if (!isRecord(entry) ||
+            typeof entry.name !== "string" ||
+            !ENV_NAME_RE.test(entry.name)) {
+            errors.push(`environment[${index}].name is not a valid environment variable name`);
+            continue;
+        }
+        names.add(entry.name);
+        const isSecret = entry.secret === true || SECRET_NAME_RE.test(entry.name);
+        if (isSecret && !secretNames.includes(entry.name)) {
+            secretNames.push(entry.name);
+        }
+    }
+    const variableNames = [...names].sort();
+    if (variableNames.length > 128)
+        errors.push("environment has more than 128 names");
+    if (errors.length)
+        return { state: "invalid", errors };
+    const toml = variableNames.length === 0
+        ? "[environment]\n"
+        : variableNames
+            .map((name) => [
+            "[[environment.variables]]",
+            `name = ${JSON.stringify(name)}`,
+            ...(secretNames.includes(name) ? ["secret = true"] : []),
+            "required = false",
+            "",
+        ].join("\n"))
+            .join("\n");
+    return { state: "valid", variableNames, secretNames, toml };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/env/parse-env.js

@@ -0,0 +1,50 @@
+/** Select dotenv assignment lines by name while keeping their original bytes for the cloud's parser.
+ *  Unselected values never cross the network boundary. This mirrors the cloud parser's line grammar. */
+export function filterEnvFileNames(text, selected) {
+    const lines = [];
+    const found = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const assignment = trimmed.startsWith("export ") ? trimmed.slice("export ".length) : trimmed;
+        const equals = assignment.indexOf("=");
+        if (equals < 0)
+            continue;
+        const name = assignment.slice(0, equals).trim();
+        if (!selected.has(name))
+            continue;
+        lines.push(line);
+        found.add(name);
+    }
+    return { text: lines.length === 0 ? "" : `${lines.join("\n")}\n`, found: [...found].sort((a, b) => a.localeCompare(b, "en")) };
+}
+/** Parse dotenv assignments using the mirror import grammar, after the caller has locally selected
+ * names. Values stay in this process and are posted one at a time to the documented write route. */
+export function parseEnvAssignments(text, selected) {
+    const entries = [];
+    for (const rawLine of text.split("\n")) {
+        const trimmed = rawLine.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const assignment = trimmed.startsWith("export ") ? trimmed.slice("export ".length) : trimmed;
+        const equals = assignment.indexOf("=");
+        if (equals < 0)
+            continue;
+        const name = assignment.slice(0, equals).trim();
+        if (name === "" || (selected !== undefined && !selected.has(name)))
+            continue;
+        const rawValue = assignment.slice(equals + 1);
+        let value = rawValue.trim();
+        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        else {
+            const comment = rawValue.search(/\s#/);
+            if (comment >= 0)
+                value = rawValue.slice(0, comment).trim();
+        }
+        entries.push({ name, value });
+    }
+    return entries;
+}

package/dist/env/settings-toml.js

@@ -0,0 +1,66 @@
+import { parse, TomlError } from "smol-toml";
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Validate TOML syntax and the repo declaration's environment variable table without printing values. */
+export function validateSettingsToml(text) {
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const line = error instanceof TomlError && typeof error.line === "number"
+            ? ` at line ${error.line}`
+            : "";
+        return { state: "invalid", errors: [`TOML could not be parsed${line}`] };
+    }
+    if (!isRecord(parsed))
+        return {
+            state: "invalid",
+            errors: ["the settings file must have a TOML table at its root"],
+        };
+    if (parsed.environment === undefined)
+        return { state: "no-source", errors: [] };
+    if (!isRecord(parsed.environment))
+        return { state: "invalid", errors: ["environment must be a table"] };
+    const section = parsed.environment;
+    if (section.variables === undefined)
+        return { state: "valid", errors: [], variableNames: [] };
+    if (!Array.isArray(section.variables))
+        return {
+            state: "invalid",
+            errors: ["environment.variables must be an array of tables"],
+        };
+    const errors = [];
+    const names = new Set();
+    const variableNames = [];
+    if (section.variables.length > 128)
+        errors.push("environment.variables has more than 128 entries");
+    for (const [index, raw] of section.variables.entries()) {
+        const prefix = `environment.variables[${index}]`;
+        if (!isRecord(raw)) {
+            errors.push(`${prefix} must be a table`);
+            continue;
+        }
+        const name = raw.name;
+        if (typeof name !== "string" || !ENV_NAME_RE.test(name)) {
+            errors.push(`${prefix}.name is not a valid environment variable name`);
+        }
+        else {
+            variableNames.push(name);
+            if (names.has(name))
+                errors.push(`${prefix}.name duplicates ${name}`);
+            names.add(name);
+        }
+        if (raw.required !== undefined && typeof raw.required !== "boolean")
+            errors.push(`${prefix}.required must be a boolean`);
+        if (raw.secret !== undefined && typeof raw.secret !== "boolean")
+            errors.push(`${prefix}.secret must be a boolean`);
+        if ("value" in raw)
+            errors.push(`${prefix}.value is not allowed; store values in the cloud`);
+    }
+    return errors.length > 0
+        ? { state: "invalid", errors }
+        : { state: "valid", errors: [], variableNames };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}