agency-lang 0.13.4 → 0.15.0

package/dist/lib/cli/local.d.ts

@@ -1,9 +1,20 @@
-import { type RefreshResult } from "../stdlib/localModels.js";
-export declare function aliasList(file?: string): import("../stdlib/localModels.js").ModelNameEntry[];
+import { type ModelNameEntry, type RefreshResult } from "../stdlib/localModels.js";
+export declare function aliasList(file?: string): ModelNameEntry[];
 export declare function aliasAdd(name: string, uri: string, file?: string): string;
 export declare function aliasRemove(name: string, file?: string): string;
+/** Deliberately ungated: browsing the catalog needs no provider package
+ *  (only download/remove do), and the pre-install experience — see what is
+ *  available, then get told what to install — is the point. */
 export declare function runList(): void;
-export declare function runDownload(value: string): Promise<void>;
+export declare const CUSTOM_CHOICE = "__custom__";
+/** Picker rows for the no-argument `agency local download`. Metadata-less
+ *  aliases get a bare name; the trailing choice lets the user type an hf: URI
+ *  or .gguf path. */
+export declare function downloadChoices(entries: ModelNameEntry[]): {
+    title: string;
+    value: string;
+}[];
+export declare function runDownload(value?: string): Promise<void>;
 export declare function runRemove(name: string): void;
 export declare function runResolve(value: string): void;
 export declare function runAliasList(): void;

package/dist/lib/cli/local.js

@@ -1,4 +1,6 @@
-import { _resolveModelName, _downloadModel, _listDownloadedModels, _listModelNames, _aliasModel, _unaliasModel, _removeModel, hasLocalModelSupport, formatGB, formatModelCatalog, _refreshCatalog, } from "../stdlib/localModels.js";
+import prompts from "prompts";
+import { _resolveModelName, _downloadModel, _listDownloadedModels, _listModelNames, _modelsCacheDir, _aliasModel, _unaliasModel, _removeModel, hasLocalModelSupport, formatGB, formatModelCatalog, formatLocalList, _refreshCatalog, } from "../stdlib/localModels.js";
+import { readDownloadManifest } from "../stdlib/localModelManifest.js";
 import { ttyColor } from "../utils/termcolors.js";
 /** Install-gate for I/O commands. Honors the AGENCY_LLAMA_PROVIDER_MODULE
  *  override the same way `requireSupport()` in `localModels.ts` does — a
@@ -31,26 +33,72 @@ export function aliasRemove(name, file) {
     }
     return inspected;
 }
+/** Deliberately ungated: browsing the catalog needs no provider package
+ *  (only download/remove do), and the pre-install experience — see what is
+ *  available, then get told what to install — is the point. */
 export function runList() {
-    gate();
-    const models = _listDownloadedModels();
-    if (models.length === 0) {
-        console.log("No models downloaded.");
-        return;
-    }
-    for (const m of models) {
-        console.log(`${m.name}\t${formatGB(m.sizeBytes)}`);
-    }
-    const total = models.reduce((sum, m) => sum + m.sizeBytes, 0);
-    console.log(`Total: ${formatGB(total)}`);
+    const dir = _modelsCacheDir();
+    console.log(formatLocalList({
+        dir,
+        entries: _listModelNames(),
+        manifest: readDownloadManifest(dir),
+        files: _listDownloadedModels(),
+    }));
+}
+export const CUSTOM_CHOICE = "__custom__";
+/** Picker rows for the no-argument `agency local download`. Metadata-less
+ *  aliases get a bare name; the trailing choice lets the user type an hf: URI
+ *  or .gguf path. */
+export function downloadChoices(entries) {
+    const rows = entries.map((e) => ({
+        title: e.params !== undefined && e.sizeBytes !== undefined
+            ? `${e.name}  (${e.params}, ${formatGB(e.sizeBytes)})`
+            : e.name,
+        value: e.name,
+    }));
+    return [...rows, { title: "custom (hf: URI or .gguf path)…", value: CUSTOM_CHOICE }];
 }
 export async function runDownload(value) {
     gate();
+    let picked = value;
+    if (picked === undefined) {
+        // Prompting needs BOTH ends of the terminal: a TTY stdout to draw on and
+        // a TTY stdin to read from (`agency local download < /dev/null` from a
+        // terminal has a TTY stdout but nothing to read).
+        if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+            // A script that reaches this point asked for a download and did not
+            // get one — print what is available and fail.
+            console.log(formatModelCatalog());
+            console.error("Pass a model: agency local download <name>");
+            process.exit(1);
+        }
+        const answer = await prompts({
+            type: "select",
+            name: "model",
+            message: "Which model do you want to download?",
+            choices: downloadChoices(_listModelNames()),
+        });
+        // Cancellation can surface as a missing key or as null — treat both as
+        // "exit 0, nothing downloaded".
+        if (answer.model == null)
+            return;
+        picked = answer.model;
+        if (picked === CUSTOM_CHOICE) {
+            const custom = await prompts({
+                type: "text",
+                name: "value",
+                message: "hf: URI or .gguf path:",
+            });
+            if (custom.value == null || custom.value === "")
+                return;
+            picked = custom.value;
+        }
+    }
     // Show the source it resolved to (the hf: URI for a name/alias) and the
     // local path it landed at. For a .gguf-path input the two are the same, so
     // the source line is skipped.
-    const source = _resolveModelName(value);
-    const modelPath = await _downloadModel(value);
+    const source = _resolveModelName(picked);
+    const modelPath = await _downloadModel(picked);
     if (source !== modelPath) {
         console.log(`source: ${source}`);
     }

package/dist/lib/cli/localFlag.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedModelFlag } from "../config.js";
+/** Turn `agency run --local <value>` into the shared model-flag shape:
+ *  resolve the name (curated / alias / hf: URI / .gguf path), download and
+ *  verify if needed (progress prints here, in the parent, before the program
+ *  starts), and pin the llama-cpp provider. Errors (package missing, unknown
+ *  name, failed download) carry user-ready messages from localModels.
+ *
+ *  The path is absolutized before it is baked into config: LlamaCPP rejects a
+ *  bare separator-less filename (ambiguous with a model name), which is what
+ *  a user-supplied `--local model.gguf` would otherwise arrive as, and an
+ *  absolute path also keeps the child process independent of cwd drift. */
+export declare function resolveLocalRunFlag(value: string): Promise<ResolvedModelFlag>;

package/dist/lib/cli/localFlag.js

@@ -0,0 +1,16 @@
+import * as path from "node:path";
+import { _registerLocalModel } from "../stdlib/localModels.js";
+/** Turn `agency run --local <value>` into the shared model-flag shape:
+ *  resolve the name (curated / alias / hf: URI / .gguf path), download and
+ *  verify if needed (progress prints here, in the parent, before the program
+ *  starts), and pin the llama-cpp provider. Errors (package missing, unknown
+ *  name, failed download) carry user-ready messages from localModels.
+ *
+ *  The path is absolutized before it is baked into config: LlamaCPP rejects a
+ *  bare separator-less filename (ambiguous with a model name), which is what
+ *  a user-supplied `--local model.gguf` would otherwise arrive as, and an
+ *  absolute path also keeps the child process independent of cwd drift. */
+export async function resolveLocalRunFlag(value) {
+    const modelPath = await _registerLocalModel(value);
+    return { model: path.resolve(modelPath), explicitProvider: "llama-cpp" };
+}

package/dist/lib/cli/remote/commands/deploy.d.ts

@@ -5,4 +5,8 @@ export type RemoteDeployOptions = {
     apiKeyEnv?: string;
     dryRun?: boolean;
 };
-export declare function runDeploy(file: string, options: RemoteDeployOptions, context: RemoteCommandContext): Promise<void>;
+/** What actually happened, for callers that gate follow-up work on a real
+ *  upload (schedule add's deploy-if-missing). A deploy error never produces an
+ *  outcome — that path exits the process. */
+export type RunDeployOutcome = "deployed" | "aborted" | "preview";
+export declare function runDeploy(file: string, options: RemoteDeployOptions, context: RemoteCommandContext): Promise<RunDeployOutcome>;

package/dist/lib/cli/remote/commands/deploy.js

@@ -17,7 +17,7 @@ export async function runDeploy(file, options, context) {
             color.dim("Nodes and functions must be marked 'export' to be served."));
         if (!(await confirmDeployWithoutExports({ dryRun: options.dryRun }))) {
             console.log("Aborted.");
-            return;
+            return "aborted";
         }
     }
     const outcome = await deploy(file, context.config, options);
@@ -26,16 +26,17 @@ export async function runDeploy(file, options, context) {
         process.exit(1);
     }
     if (outcome.kind !== "deployed") {
-        return; // a --dry-run preview never writes a binding
+        return "preview"; // a --dry-run preview never writes a binding
     }
     const base = serveBaseUrl(outcome.endpointUrls);
     const address = base ? parseServeBaseUrl(base) : null;
     if (!address) {
         console.log(color.yellow("Deployed, but could not derive a serve URL to link."));
-        return;
+        return "deployed";
     }
     writeBinding(context.configPath, address);
     console.log(`\n${color.green("Linked")} this directory to ${color.bold(address.filename)}.`);
+    return "deployed";
 }
 function tryCountExports(file, config) {
     try {

package/dist/lib/cli/remote/commands/secrets.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectCommandOptions, RemoteCommandContext } from "./util.js";
+import { SecretRequestError } from "../../statelog/secretsClient.js";
+import type { SecretValueSources } from "../secretsInput.js";
+/** The set recipe's terminal dependencies, injected by the Commander action
+ *  and faked in tests. Same fields as SecretValueSources minus fromEnv, which
+ *  arrives via options. */
+export type SecretsSetIO = Omit<SecretValueSources, "fromEnv">;
+export type SecretsSetResult = {
+    kind: "set";
+} | {
+    kind: "canceled";
+};
+/** THE one presenter for SecretRequestError, used by all four recipes
+ *  (including every collected import failure): redacts any additional known
+ *  values BEFORE terminal-safe escaping, then appends the trusted one-line
+ *  full-access-key guidance on status 401/403. Stays one line so import
+ *  summaries keep one outcome per line. */
+export declare function presentSecretError(error: SecretRequestError, sensitiveValues?: string[]): string;
+export declare function runSecretsSet(name: string, options: ProjectCommandOptions & {
+    fromEnv?: string;
+}, context: RemoteCommandContext, io: SecretsSetIO): Promise<SecretsSetResult>;
+export declare function runSecretsList(options: ProjectCommandOptions, context: RemoteCommandContext): Promise<void>;
+export declare function runSecretsRm(name: string, options: ProjectCommandOptions, context: RemoteCommandContext): Promise<void>;
+export type ImportResult = {
+    kind: "declined";
+} | {
+    kind: "succeeded";
+} | {
+    kind: "failed";
+};
+export type SecretsImportIO = {
+    stdinIsTty: boolean;
+    readStdin: () => Promise<string>;
+    confirm: (question: string) => Promise<boolean>;
+};
+export declare function runSecretsImport(file: string | undefined, options: ProjectCommandOptions, context: RemoteCommandContext, io: SecretsImportIO): Promise<ImportResult>;

package/dist/lib/cli/remote/commands/secrets.js

@@ -0,0 +1,178 @@
+// `agency remote secrets` — thin recipes over the sealed secrets client. The
+// store is write-only (no route returns a value), and these recipes uphold the
+// CLI's matching invariants: a value reaches `set` only through injected seams
+// (never argv), and no code path prints one — presentSecretError is the single
+// place that composes redaction, terminal-safe escaping, and trusted auth
+// guidance, in that order. Recipes render and return semantic outcomes; the
+// Commander actions own process.exitCode.
+import * as fs from "fs";
+import * as path from "path";
+import { color } from "../../../utils/termcolors.js";
+import { resolveProjectTarget, fail } from "./util.js";
+import { createSecretsClient, SecretRequestError } from "../../statelog/secretsClient.js";
+import { redactValues } from "../../statelog/redact.js";
+import { resolveSecretValue, parseEnvSource, terminalSafe } from "../secretsInput.js";
+/** THE one presenter for SecretRequestError, used by all four recipes
+ *  (including every collected import failure): redacts any additional known
+ *  values BEFORE terminal-safe escaping, then appends the trusted one-line
+ *  full-access-key guidance on status 401/403. Stays one line so import
+ *  summaries keep one outcome per line. */
+export function presentSecretError(error, sensitiveValues = []) {
+    const safe = terminalSafe(redactValues(error.message, sensitiveValues));
+    if (error.status === 401 || error.status === 403) {
+        return `${safe} — Secret management needs a full-access API key; invoke-only keys and sessions are rejected.`;
+    }
+    return safe;
+}
+export async function runSecretsSet(name, options, context, io) {
+    const target = resolveProjectTarget(context, options);
+    const resolved = await resolveSecretValue(name, { ...io, fromEnv: options.fromEnv });
+    if (resolved.kind === "canceled") {
+        console.log("Canceled.");
+        return { kind: "canceled" };
+    }
+    if (resolved.kind === "error") {
+        fail(resolved.message);
+    }
+    const client = createSecretsClient(target.origin, target.projectSlug, target.apiKey);
+    try {
+        await client.set(name, resolved.value);
+    }
+    catch (error) {
+        failSecretRequest(error);
+    }
+    console.log(`${color.green("Set")} secret ${terminalSafe(name)}.`);
+    // The hint shows real call-site syntax, so the name renders as an actual
+    // string literal — JSON.stringify quotes AND escapes it in one step (a
+    // terminalSafe'd name would end up double-quoted here).
+    console.log(`Available to hosted runs as env(${JSON.stringify(name)}) from the next invocation.`);
+    return { kind: "set" };
+}
+export async function runSecretsList(options, context) {
+    const target = resolveProjectTarget(context, options);
+    const client = createSecretsClient(target.origin, target.projectSlug, target.apiKey);
+    let secrets;
+    try {
+        secrets = await client.list();
+    }
+    catch (error) {
+        failSecretRequest(error);
+    }
+    console.log(formatSecretsTable(secrets));
+}
+export async function runSecretsRm(name, options, context) {
+    const target = resolveProjectTarget(context, options);
+    const client = createSecretsClient(target.origin, target.projectSlug, target.apiKey);
+    try {
+        await client.delete(name);
+    }
+    catch (error) {
+        failSecretRequest(error);
+    }
+    console.log(`${color.green("Removed")} secret ${terminalSafe(name)}.`);
+}
+export async function runSecretsImport(file, options, context, io) {
+    const target = resolveProjectTarget(context, options);
+    const fromStdin = file === "-";
+    const sourceName = fromStdin ? "<stdin>" : (file ?? ".env");
+    // The file argument is user/argv-controlled display text like any other.
+    const safeSource = terminalSafe(sourceName);
+    let text;
+    if (fromStdin) {
+        text = await io.readStdin();
+    }
+    else {
+        const sourcePath = path.resolve(process.cwd(), sourceName);
+        try {
+            text = fs.readFileSync(sourcePath, "utf-8");
+        }
+        catch (error) {
+            fail(`Could not read ${safeSource}: ${errorMessage(error)}`);
+        }
+    }
+    const { entries } = parseEnvSource(text);
+    if (entries.length === 0) {
+        fail(`No variables found in ${safeSource}.`);
+    }
+    // Confirmation is for FILE sources on a TTY only. An explicit `-` never
+    // prompts: after an interactive stdin entry the stream is exhausted at EOF,
+    // and choosing `-` is itself the authorization.
+    if (!fromStdin && io.stdinIsTty) {
+        const plural = entries.length === 1 ? "" : "s";
+        console.log(`Import ${entries.length} secret${plural} into project ${target.projectSlug} from ${safeSource}:`);
+        for (const entry of entries) {
+            console.log(`  ${terminalSafe(entry.name)}`);
+        }
+        if (!(await io.confirm("Continue?"))) {
+            console.log("Canceled.");
+            return { kind: "declined" };
+        }
+    }
+    const allValues = entries.map((entry) => entry.value);
+    const client = createSecretsClient(target.origin, target.projectSlug, target.apiKey);
+    const outcomes = [];
+    for (const entry of entries) {
+        if (entry.value === "") {
+            outcomes.push({ name: entry.name, ok: false, message: "empty value — nothing sent" });
+            continue;
+        }
+        try {
+            // The whole batch joins the FIRST redaction pass: a response echoing a
+            // DIFFERENT import's value that overlaps this one would otherwise be
+            // partially destroyed before the presenter's pass could match it.
+            await client.set(entry.name, entry.value, { alsoRedact: allValues });
+            outcomes.push({ name: entry.name, ok: true });
+        }
+        catch (error) {
+            if (!(error instanceof SecretRequestError)) {
+                throw error;
+            }
+            outcomes.push({
+                name: entry.name,
+                ok: false,
+                message: presentSecretError(error, allValues),
+            });
+        }
+    }
+    renderImportSummary(outcomes);
+    return outcomes.some((outcome) => !outcome.ok) ? { kind: "failed" } : { kind: "succeeded" };
+}
+function renderImportSummary(outcomes) {
+    const failed = outcomes.filter((outcome) => !outcome.ok);
+    const setCount = outcomes.length - failed.length;
+    if (failed.length === 0) {
+        const plural = setCount === 1 ? "" : "s";
+        console.log(`${color.green("Imported")} ${setCount} secret${plural}.`);
+        return;
+    }
+    console.log(`Imported ${setCount} of ${outcomes.length}; ${failed.length} failed:`);
+    for (const outcome of failed) {
+        console.log(`  ${terminalSafe(outcome.name)}: ${outcome.message}`);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function failSecretRequest(error) {
+    if (!(error instanceof SecretRequestError)) {
+        throw error;
+    }
+    fail(presentSecretError(error));
+}
+function formatSecretsTable(secrets) {
+    if (secrets.length === 0) {
+        return "No secrets set for this project. Use 'agency remote secrets set <NAME>' to add one.";
+    }
+    const rows = secrets.map((secret) => ({
+        name: terminalSafe(secret.name),
+        created: secret.createdAt.slice(0, 10),
+        updated: secret.updatedAt.slice(0, 10),
+    }));
+    const headers = { name: "Name", created: "Created", updated: "Updated" };
+    const columns = ["name", "created", "updated"];
+    const width = (column) => Math.max(headers[column].length, ...rows.map((row) => row[column].length)) + 2;
+    const render = (row) => columns
+        .map((column, index) => index === columns.length - 1 ? row[column] : row[column].padEnd(width(column)))
+        .join("");
+    return [render(headers), ...rows.map(render)].join("\n");
+}

package/dist/lib/cli/remote/confirmation.d.ts

@@ -3,4 +3,13 @@ export type ConfirmDeployOptions = {
     isTty?: boolean;
     prompt?: (question: string) => Promise<boolean>;
 };
+/** The deploy policy: a dry-run and a non-TTY run bypass the prompt and
+ *  proceed — only an interactive TTY asks. */
 export declare function confirmDeployWithoutExports(options?: ConfirmDeployOptions): Promise<boolean>;
+/** The raw readline yes/no lifecycle, policy-free. */
+export declare function confirmQuestion(question: string): Promise<boolean>;
+/** Hidden-input prompt for a secret value. Resolves undefined on cancellation
+ *  (ctrl-C / EOF) — `prompts` omits the answer key then — and preserves an
+ *  empty entry as "" so the caller can distinguish "typed nothing" from
+ *  "canceled". The name is untrusted display text and rendered terminal-safe. */
+export declare function promptSecretValue(name: string): Promise<string | undefined>;

package/dist/lib/cli/remote/confirmation.js

@@ -1,8 +1,13 @@
-// The "deploy an agent with no callable endpoints?" gate. Owns the TTY/readline
-// mechanics; `runDeploy` only asks whether it should proceed. Per Revision 2 a
-// dry-run and a non-TTY run bypass the prompt and proceed — only an interactive
-// TTY asks.
+// The remote commands' concrete terminal-prompt adapters: the raw yes/no
+// readline lifecycle, the hidden secret-value prompt, and the deploy-specific
+// "no callable endpoints?" gate built on top. This module owns terminal
+// mechanics only — each command keeps its own policy (when to ask, what a
+// decline means).
 import * as readline from "node:readline/promises";
+import prompts from "prompts";
+import { terminalSafe } from "./secretsInput.js";
+/** The deploy policy: a dry-run and a non-TTY run bypass the prompt and
+ *  proceed — only an interactive TTY asks. */
 export async function confirmDeployWithoutExports(options = {}) {
     if (options.dryRun) {
         return true;
@@ -11,10 +16,11 @@ export async function confirmDeployWithoutExports(options = {}) {
     if (!isTty) {
         return true;
     }
-    const prompt = options.prompt ?? defaultPrompt;
+    const prompt = options.prompt ?? confirmQuestion;
     return prompt("Upload anyway?");
 }
-async function defaultPrompt(question) {
+/** The raw readline yes/no lifecycle, policy-free. */
+export async function confirmQuestion(question) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
         const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
@@ -24,3 +30,15 @@ async function defaultPrompt(question) {
         rl.close();
     }
 }
+/** Hidden-input prompt for a secret value. Resolves undefined on cancellation
+ *  (ctrl-C / EOF) — `prompts` omits the answer key then — and preserves an
+ *  empty entry as "" so the caller can distinguish "typed nothing" from
+ *  "canceled". The name is untrusted display text and rendered terminal-safe. */
+export async function promptSecretValue(name) {
+    const response = await prompts({
+        type: "invisible",
+        name: "value",
+        message: `Enter value for ${terminalSafe(name)}:`,
+    });
+    return typeof response.value === "string" ? response.value : undefined;
+}

package/dist/lib/cli/remote/secretsInput.d.ts

@@ -0,0 +1,54 @@
+export type SecretValueSources = {
+    /** --from-env VAR: the NAME of a local environment variable to copy. */
+    fromEnv?: string;
+    stdinIsTty: boolean;
+    readStdin: () => Promise<string>;
+    /** Hidden prompt; resolves undefined when the user cancels (ctrl-C / EOF). */
+    promptHidden: (name: string) => Promise<string | undefined>;
+    env: NodeJS.ProcessEnv;
+};
+export type SecretValueResult = {
+    kind: "value";
+    value: string;
+} | {
+    kind: "canceled";
+} | {
+    kind: "error";
+    message: string;
+};
+/** Where a secret's value comes from, in precedence order: --from-env wins;
+ *  else piped stdin; else the hidden TTY prompt. Never argv. */
+export declare function resolveSecretValue(name: string, sources: SecretValueSources): Promise<SecretValueResult>;
+/** One terminal "\r\n" or "\n" removed — exactly one, so a value meant to keep
+ *  a final newline supplies two (printf 'value\n\n'). Interior newlines are
+ *  untouched. */
+export declare function stripOneTrailingNewline(text: string): string;
+export type ParsedEnvSource = {
+    /** First-insertion key order; on a duplicate key the LAST assignment's value
+     *  wins (in the original position). No duplicate reporting — a `B=` line
+     *  inside a multiline quoted value is NOT an assignment, and
+     *  last-value-wins is the behavior that matters. */
+    entries: {
+        name: string;
+        value: string;
+    }[];
+};
+/** A small, OWNED dotenv parser. Deliberately not node:util's parseEnv: its
+ *  quoted-value handling differs across Node releases inside the supported
+ *  engine range (22.13.0 mis-splits `B="x=y"` into a bogus extra entry), and
+ *  secret values must parse identically on every supported version. Semantics
+ *  (pinned by tests): `NAME=value` lines; optional `export ` prefix; `#`
+ *  comments and blank lines skipped; single- or double-quoted values may span
+ *  lines and keep `=`/`#` literally; quoted content is LITERAL (no escape
+ *  expansion); unquoted values run to end of line, trimmed. Never touches
+ *  process.env. */
+export declare function parseEnvSource(text: string): ParsedEnvSource;
+/** Single-line, terminal-safe rendering for untrusted display text (names,
+ *  server messages): a string containing terminal-control characters is
+ *  JSON-quoted so it cannot manipulate the terminal; plain strings pass
+ *  through unchanged. "Control" covers C0, DEL, and the C1 range (U+009B is a
+ *  bare CSI) plus the U+2028/U+2029 line separators — and because
+ *  JSON.stringify escapes only C0, the quoted form is post-processed so every
+ *  such character ends up as a \\uXXXX escape. Always applied AFTER
+ *  redaction. */
+export declare function terminalSafe(text: string): string;

package/dist/lib/cli/remote/secretsInput.js

@@ -0,0 +1,123 @@
+// Pure input handling for the remote secrets commands — a sibling of args.ts.
+// No terminal, no `prompts`, no process globals: every environmental input
+// (TTY-ness, stdin, the hidden prompt, the env) arrives injected, so the
+// precedence rules and parsing are testable without a terminal. The concrete
+// adapters live in confirmation.ts.
+/** Where a secret's value comes from, in precedence order: --from-env wins;
+ *  else piped stdin; else the hidden TTY prompt. Never argv. */
+export async function resolveSecretValue(name, sources) {
+    if (sources.fromEnv !== undefined) {
+        const value = sources.env[sources.fromEnv];
+        if (value === undefined || value === "") {
+            return {
+                kind: "error",
+                message: `$${sources.fromEnv} is not set (or is empty) — --from-env needs a non-empty variable.`,
+            };
+        }
+        return { kind: "value", value };
+    }
+    if (!sources.stdinIsTty) {
+        const value = stripOneTrailingNewline(await sources.readStdin());
+        if (value === "") {
+            return {
+                kind: "error",
+                message: "No value on stdin — pipe a non-empty value, or run interactively for a hidden prompt.",
+            };
+        }
+        return { kind: "value", value };
+    }
+    const entered = await sources.promptHidden(name);
+    if (entered === undefined) {
+        return { kind: "canceled" };
+    }
+    if (entered === "") {
+        return { kind: "error", message: "Secret value must not be empty." };
+    }
+    return { kind: "value", value: entered };
+}
+/** One terminal "\r\n" or "\n" removed — exactly one, so a value meant to keep
+ *  a final newline supplies two (printf 'value\n\n'). Interior newlines are
+ *  untouched. */
+export function stripOneTrailingNewline(text) {
+    if (text.endsWith("\r\n")) {
+        return text.slice(0, -2);
+    }
+    if (text.endsWith("\n")) {
+        return text.slice(0, -1);
+    }
+    return text;
+}
+const NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A small, OWNED dotenv parser. Deliberately not node:util's parseEnv: its
+ *  quoted-value handling differs across Node releases inside the supported
+ *  engine range (22.13.0 mis-splits `B="x=y"` into a bogus extra entry), and
+ *  secret values must parse identically on every supported version. Semantics
+ *  (pinned by tests): `NAME=value` lines; optional `export ` prefix; `#`
+ *  comments and blank lines skipped; single- or double-quoted values may span
+ *  lines and keep `=`/`#` literally; quoted content is LITERAL (no escape
+ *  expansion); unquoted values run to end of line, trimmed. Never touches
+ *  process.env. */
+export function parseEnvSource(text) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    const values = new Map();
+    for (let index = 0; index < lines.length; index++) {
+        let line = lines[index].trim();
+        if (line === "" || line.startsWith("#")) {
+            continue;
+        }
+        if (line.startsWith("export ")) {
+            line = line.slice("export ".length).trim();
+        }
+        const equals = line.indexOf("=");
+        if (equals <= 0) {
+            continue;
+        }
+        const name = line.slice(0, equals).trim();
+        if (!NAME_PATTERN.test(name)) {
+            continue;
+        }
+        const rest = line.slice(equals + 1).trim();
+        if (rest.startsWith('"') || rest.startsWith("'")) {
+            const quote = rest[0];
+            let accumulated = rest.slice(1);
+            let closing = accumulated.indexOf(quote);
+            while (closing === -1 && index + 1 < lines.length) {
+                index++;
+                accumulated += `\n${lines[index]}`;
+                closing = accumulated.indexOf(quote);
+            }
+            values.set(name, closing === -1 ? accumulated : accumulated.slice(0, closing));
+        }
+        else {
+            values.set(name, rest);
+        }
+    }
+    return { entries: [...values.entries()].map(([name, value]) => ({ name, value })) };
+}
+/** Single-line, terminal-safe rendering for untrusted display text (names,
+ *  server messages): a string containing terminal-control characters is
+ *  JSON-quoted so it cannot manipulate the terminal; plain strings pass
+ *  through unchanged. "Control" covers C0, DEL, and the C1 range (U+009B is a
+ *  bare CSI) plus the U+2028/U+2029 line separators — and because
+ *  JSON.stringify escapes only C0, the quoted form is post-processed so every
+ *  such character ends up as a \\uXXXX escape. Always applied AFTER
+ *  redaction. */
+export function terminalSafe(text) {
+    if (![...text].some((character) => isTerminalUnsafe(character.codePointAt(0) ?? 0))) {
+        return text;
+    }
+    let escaped = "";
+    for (const character of JSON.stringify(text)) {
+        const code = character.codePointAt(0) ?? 0;
+        escaped += isTerminalUnsafe(code)
+            ? `\\u${code.toString(16).padStart(4, "0")}`
+            : character;
+    }
+    return escaped;
+}
+function isTerminalUnsafe(code) {
+    return (code < 0x20 ||
+        (code >= 0x7f && code <= 0x9f) ||
+        code === 0x2028 ||
+        code === 0x2029);
+}

package/dist/lib/cli/schedule/cron.d.ts

@@ -1,4 +1,5 @@
 export declare const PRESETS: Record<string, string>;
+export declare function canonicalPreset(preset: string): string;
 export declare function presetToCron(preset: string): string;
 export declare function validateCron(expr: string): boolean;
 export declare function resolveCron(opts: {