@sns-myagent/cli 0.2.0

package/src/cli/entry.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+// Single-file CLI entry for `bun build --compile`.
+// Mirrors bin/snscoder (Node dev shim) but is a TS module so Bun can bundle
+// all transitive imports into the binary.
+
+import { ensureConfig } from "../config/loader.js";
+import { runCli } from "./index.js";
+import { startTelegramAdapter } from "../adapters/telegram/index.js";
+
+const commandsNeedingConfig = new Set(["config", "chat", "telegram"]);
+const argv = process.argv.slice(2);
+const head = argv[0];
+
+// Auto-boot the Telegram polling adapter when a token is present and the
+// user is not explicitly running a different subcommand. Disable with
+// SNS_TELEGRAM_AUTOSTART=0.
+function maybeAutostartTelegram(): void {
+	if (head === "telegram") return; // explicit start/stop handles its own lifecycle
+	if (process.env.SNS_TELEGRAM_AUTOSTART === "0") return;
+	const token = process.env.SNS_TELEGRAM_BOT_TOKEN;
+	if (!token) return;
+	startTelegramAdapter(token, { autostart: true });
+}
+
+try {
+	if (head !== undefined && commandsNeedingConfig.has(head) && !process.env.SNS_NO_BOOTSTRAP) {
+		ensureConfig();
+	}
+	maybeAutostartTelegram();
+	const code = await runCli(argv);
+	if (code !== 0) process.exit(code);
+} catch (err) {
+	const e = err as Error;
+	const msg = e.message ? e.message : String(err);
+	process.stderr.write(`\u2717 snscoder crashed: ${msg}\n`);
+	if (process.env.SNS_DEBUG) {
+		process.stderr.write("\n" + (e.stack ?? "") + "\n");
+	}
+	process.exit(1);
+}

package/src/cli/extension-flags.ts

@@ -0,0 +1,48 @@
+import { type Args, parseArgs } from "./args";
+
+/**
+ * Minimal extension-runner surface needed to resolve CLI flag values. The real
+ * `ExtensionRunner` satisfies this structurally; depending only on the surface
+ * keeps this module free of the heavier runner/session imports and unit-testable
+ * with a fake.
+ */
+export interface ExtensionFlagSink {
+	getFlags(): Map<string, { type: "boolean" | "string" }>;
+	setFlagValue(name: string, value: boolean | string): void;
+}
+
+/**
+ * Resolve extension-registered CLI flags from `rawArgs` once the flag set is
+ * known, push the resolved values onto the sink, and return the parsed
+ * {@link Args} (whose `messages` and `fileArgs` now reflect those flags).
+ *
+ * The startup parse runs before extensions load, so it cannot recognise their
+ * flags: a string flag's value (`--spawn-peer reviewer` or `--spawn-peer=reviewer`)
+ * is otherwise left in `messages` and leaks into the initial prompt. Re-parsing
+ * here — through the *same* {@link parseArgs} the startup pass uses, now seeded
+ * with the registered flags — consumes every flag form (`--flag`, `--flag value`,
+ * `--flag=value`).
+ *
+ * {@link parseArgs} lets a registered flag shadow a same-named built-in, so even
+ * a built-in-colliding flag (e.g. plan-mode's boolean `--plan`, which would
+ * otherwise hit the built-in plan-model branch) is parsed with the extension's
+ * semantics and surfaces in `unknownFlags` — without consuming the following
+ * message or overwriting the built-in field. No built-in name list to maintain.
+ *
+ * Returns `null` when there is no sink or no registered extension flags, in
+ * which case the caller keeps its original startup parse (an extension-aware
+ * re-parse would be identical anyway).
+ */
+export function applyExtensionFlags(runner: ExtensionFlagSink | undefined, rawArgs: string[]): Args | null {
+	const extensionFlags = runner?.getFlags();
+	if (!runner || !extensionFlags || extensionFlags.size === 0) {
+		return null;
+	}
+	const parsed = parseArgs(rawArgs, extensionFlags);
+	// `parseArgs` only records registered extension flags in `unknownFlags`, so
+	// every entry here is a flag this runner owns that was actually passed.
+	for (const [name, value] of parsed.unknownFlags) {
+		runner.setFlagValue(name, value);
+	}
+	return parsed;
+}

package/src/cli/file-processor.ts

@@ -0,0 +1,133 @@
+/**
+ * Process @file CLI arguments into text, document content, and image attachments
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { getProjectDir, isEnoent, readImageMetadata } from "@oh-my-pi/pi-utils";
+import chalk from "chalk";
+import { resolveReadPath } from "../tools/path-utils";
+import { formatBytes } from "../tools/render-utils";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { convertFileWithMarkit } from "../utils/markit";
+
+// Keep CLI startup responsive and avoid OOM when users pass huge files.
+// If a file exceeds these limits, we include it as a path-only <file/> block.
+const MAX_CLI_TEXT_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_CLI_IMAGE_BYTES = 25 * 1024 * 1024; // 25MB
+const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
+
+export interface ProcessedFiles {
+	text: string;
+	images: ImageContent[];
+}
+
+export interface ProcessFileOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+}
+
+/** Process @file arguments into text, document content, and image attachments */
+export async function processFileArguments(fileArgs: string[], options?: ProcessFileOptions): Promise<ProcessedFiles> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	let text = "";
+	const images: ImageContent[] = [];
+
+	for (const fileArg of fileArgs) {
+		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
+		const absolutePath = path.resolve(resolveReadPath(fileArg, getProjectDir()));
+
+		const stat = fs.statSync(absolutePath, { throwIfNoEntry: false });
+		if (!stat) {
+			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+			process.exit(1);
+		}
+
+		const imageMetadata = await readImageMetadata(absolutePath);
+		const mimeType = imageMetadata?.mimeType;
+		const ext = path.extname(absolutePath).toLowerCase();
+		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
+		if (stat.size > maxBytes) {
+			console.error(
+				chalk.yellow(`Warning: Skipping file contents (too large: ${formatBytes(stat.size)}): ${absolutePath}`),
+			);
+			text += `<file name="${absolutePath}">(skipped: too large, ${formatBytes(stat.size)})</file>\n`;
+			continue;
+		}
+
+		// Read file, handling not-found gracefully
+		let buffer: Uint8Array;
+		try {
+			buffer = await Bun.file(absolutePath).bytes();
+		} catch (err) {
+			if (isEnoent(err)) {
+				console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+				process.exit(1);
+			}
+			throw err;
+		}
+		if (buffer.length === 0) {
+			continue;
+		}
+
+		if (mimeType) {
+			// Handle image file
+			const base64Content = buffer.toBase64();
+			let attachment: ImageContent;
+			let dimensionNote: string | undefined;
+
+			if (autoResizeImages) {
+				try {
+					const resized = await resizeImage({ type: "image", data: base64Content, mimeType });
+					dimensionNote = formatDimensionNote(resized);
+					attachment = {
+						type: "image",
+						mimeType: resized.mimeType,
+						data: resized.data,
+					};
+				} catch {
+					// Fall back to original image on resize failure
+					attachment = {
+						type: "image",
+						mimeType,
+						data: base64Content,
+					};
+				}
+			} else {
+				attachment = {
+					type: "image",
+					mimeType,
+					data: base64Content,
+				};
+			}
+
+			images.push(attachment);
+
+			// Add text reference to image with optional dimension note
+			if (dimensionNote) {
+				text += `<file name="${absolutePath}">${dimensionNote}</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}"></file>\n`;
+			}
+		} else if (CONVERTIBLE_EXTENSIONS.has(ext)) {
+			const result = await convertFileWithMarkit(absolutePath);
+			if (result.ok) {
+				text += `<file name="${absolutePath}">\n${result.content}\n</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}">[Cannot read ${ext} file: ${result.error || "conversion failed"}]</file>\n`;
+			}
+		} else {
+			// Handle text file
+			try {
+				const content = new TextDecoder().decode(buffer);
+				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red(`Error: Could not read file ${absolutePath}: ${message}`));
+				process.exit(1);
+			}
+		}
+	}
+
+	return { text, images };
+}

package/src/cli/flag-tables.ts

@@ -0,0 +1,322 @@
+/**
+ * Single source of truth for argv flag classification, shared by:
+ *   - `parseArgs` in `./args.ts` (the launch-time CLI parser)
+ *   - `extractProfileFlags` in `./profile-bootstrap.ts` (the early
+ *     `--profile` / `--alias` pre-parser)
+ *
+ * `parseArgs` dispatches string-valued flags by looking up their setter in
+ * {@link STRING_SETTERS}. Optional-value flags use {@link OPTIONAL_FLAGS} so
+ * per-flag quirks (currently empty-string rejection for `--resume`) live here
+ * instead of being hard-coded in the dispatch loop.
+ *
+ * The bootstrap doesn't dispatch — it only needs to know which flags consume
+ * a value — so it consults {@link STRING_VALUE_FLAGS} and
+ * {@link OPTIONAL_VALUE_FLAGS}, both derived from `Object.keys(...)` on the
+ * setter/config records below.
+ *
+ * The deliberate consequence: a string-valued flag exists in this CLI surface
+ * iff it has an entry here. Adding a new string-valued flag means adding a
+ * setter/config entry in this file; both `args.ts` and the bootstrap pick it
+ * up automatically, so the two cannot drift out of sync.
+ *
+ * IMPORT RULE: this module MUST NOT import any runtime value from
+ * `@oh-my-pi/pi-utils` (or anything that transitively does). That package's
+ * `env.ts` eagerly loads `.env` files from `getAgentDir()` during module
+ * initialization, which would race the profile bootstrap. Type-only imports
+ * are erased at runtime and are therefore safe.
+ *
+ * If a setter needs runtime dependencies (logging, validators, lookup
+ * tables), they're passed in through {@link ParseDeps} and `args.ts` wires the
+ * real implementations at the dispatch site.
+ */
+
+import type { Effort } from "@oh-my-pi/pi-ai";
+import type { Args } from "./args";
+
+/**
+ * Runtime dependencies injected into setters that need to validate input or
+ * warn about bad values. `args.ts` constructs one object at module load and
+ * passes it to each {@link STRING_SETTERS} call.
+ *
+ * Keeping these out of the setter closures means this module stays free of
+ * runtime imports from `@oh-my-pi/pi-utils`, which is the whole reason it can
+ * be safely imported by `profile-bootstrap.ts` before `setProfile` runs.
+ */
+export interface ParseDeps {
+	logger: { warn: (message: string, meta?: Record<string, unknown>) => void };
+	parseEffort: (value: string | null | undefined) => Effort | undefined;
+	builtinToolNames: readonly string[];
+	thinkingEfforts: readonly string[];
+}
+
+export type StringSetter = (result: Args, value: string, deps: ParseDeps) => void;
+
+/**
+ * Setter for a flag that may or may not consume the next argv token.
+ * Receives `undefined` for the bare form (`--resume` with no value, etc.).
+ */
+export type OptionalSetter = (result: Args, value: string | undefined) => void;
+
+/**
+ * Per-flag optional-value consumption policy.
+ *
+ * Every optional flag always rejects tokens that start with `-` — that shared
+ * rule lives in the dispatch site. These booleans capture the *additional*
+ * per-flag quirks:
+ *
+ * - `rejectEmpty`: treat `""` like “no value provided”. Needed for
+ *   `--resume` / `-r` / `--session`. Without it, an empty string
+ *   gets consumed as the session prefix and downstream resolution can match
+ *   every session.
+ */
+export interface OptionalFlagConfig {
+	set: OptionalSetter;
+	rejectEmpty?: boolean;
+}
+
+// Shared setters for flags that alias the same field.
+const setExtension: StringSetter = (result, value) => {
+	result.extensions = result.extensions ?? [];
+	result.extensions.push(value);
+};
+
+const setResume: OptionalSetter = (result, value) => {
+	result.resume = value !== undefined ? value : true;
+};
+
+/**
+ * Setters for flags with string values. Most built-ins consume the next argv
+ * token even when it starts with `-`; flags listed in
+ * {@link EXTENSION_SHADOWABLE_STRING_FLAGS} use extension-style consumption so
+ * a registered boolean extension can shadow them before profile bootstrap.
+ */
+export const STRING_SETTERS: Record<string, StringSetter> = {
+	"--cwd": (result, value) => {
+		result.cwd = value;
+	},
+	"--config": (result, value) => {
+		result.config = [...(result.config ?? []), value];
+	},
+	"--mode": (result, value) => {
+		if (value === "text" || value === "json" || value === "rpc" || value === "acp" || value === "rpc-ui") {
+			result.mode = value;
+		}
+	},
+	"--fork": (result, value) => {
+		result.fork = value;
+	},
+	"--provider": (result, value) => {
+		result.provider = value;
+	},
+	"--model": (result, value) => {
+		result.model = value;
+	},
+	"--smol": (result, value) => {
+		result.smol = value;
+	},
+	"--slow": (result, value) => {
+		result.slow = value;
+	},
+	"--plan": (result, value) => {
+		result.plan = value;
+	},
+	"--max-time": (result, value, deps) => {
+		const seconds = Number(value);
+		if (Number.isFinite(seconds) && seconds > 0) {
+			result.maxTime = seconds;
+		} else {
+			deps.logger.warn("Invalid seconds passed to --max-time", { value });
+		}
+	},
+	"--api-key": (result, value) => {
+		result.apiKey = value;
+	},
+	"--system-prompt": (result, value) => {
+		result.systemPrompt = value;
+	},
+	"--append-system-prompt": (result, value) => {
+		result.appendSystemPrompt = value;
+	},
+	"--provider-session-id": (result, value) => {
+		result.providerSessionId = value;
+	},
+	"--session-dir": (result, value) => {
+		result.sessionDir = value;
+	},
+	"--models": (result, value) => {
+		result.models = value.split(",").map(s => s.trim());
+	},
+	"--tools": (result, value, deps) => {
+		const names = value
+			.split(",")
+			.map(s => s.trim().toLowerCase())
+			.filter(Boolean);
+		const valid: string[] = [];
+		for (const name of names) {
+			if (deps.builtinToolNames.includes(name)) {
+				valid.push(name);
+			} else {
+				deps.logger.warn("Unknown tool passed to --tools", {
+					tool: name,
+					validTools: deps.builtinToolNames,
+				});
+			}
+		}
+		result.tools = valid;
+	},
+	"--thinking": (result, value, deps) => {
+		const thinking = deps.parseEffort(value);
+		if (thinking !== undefined) {
+			result.thinking = thinking;
+		} else {
+			deps.logger.warn("Invalid thinking level passed to --thinking", {
+				level: value,
+				validThinkingLevels: deps.thinkingEfforts,
+			});
+		}
+	},
+	"--export": (result, value) => {
+		result.export = value;
+	},
+	"--hook": (result, value) => {
+		result.hooks = result.hooks ?? [];
+		result.hooks.push(value);
+	},
+	"--extension": setExtension,
+	"-e": setExtension,
+	"--plugin-dir": (result, value) => {
+		result.pluginDirs = result.pluginDirs ?? [];
+		result.pluginDirs.push(value);
+	},
+	"--skills": (result, value) => {
+		result.skills = value.split(",").map(s => s.trim());
+	},
+	"--approval-mode": (result, value, deps) => {
+		if (value === "always-ask" || value === "write" || value === "yolo") {
+			result.approvalMode = value;
+		} else {
+			deps.logger.warn("Invalid value passed to --approval-mode", {
+				value,
+				validValues: ["always-ask", "write", "yolo"],
+			});
+		}
+	},
+};
+
+/**
+ * Optional-value flags. Setters receive `undefined` for the bare form.
+ *
+ * The dispatch in `args.ts` applies the shared "doesn't start with `-`"
+ * check for every flag, then consults the per-flag booleans below for the
+ * remaining quirks.
+ */
+export const OPTIONAL_FLAGS: Record<string, OptionalFlagConfig> = {
+	"--resume": { set: setResume, rejectEmpty: true },
+	"-r": { set: setResume, rejectEmpty: true },
+	"--session": { set: setResume, rejectEmpty: true },
+};
+
+/**
+ * Derived from {@link STRING_SETTERS}. A flag is in this set if and only if
+ * it has a setter — by construction, drift between "the bootstrap thinks
+ * this flag accepts a value" and "the launch parser can set one" is
+ * structurally impossible.
+ */
+export const STRING_VALUE_FLAGS: ReadonlySet<string> = new Set(Object.keys(STRING_SETTERS));
+
+/**
+ * Built-in string flags known to be shadowed by bundled/common boolean
+ * extensions before extension metadata is available. They still accept a
+ * value-like successor for the built-in form (`--plan opus`), but a
+ * flag-looking successor remains a fresh flag (`--plan --profile work`).
+ */
+export const EXTENSION_SHADOWABLE_STRING_FLAGS: ReadonlySet<string> = new Set(["--plan"]);
+
+/**
+ * Derived from {@link OPTIONAL_FLAGS}. Same single-source contract as
+ * {@link STRING_VALUE_FLAGS}.
+ */
+export const OPTIONAL_VALUE_FLAGS: ReadonlySet<string> = new Set(Object.keys(OPTIONAL_FLAGS));
+
+/**
+ * Internal marker inserted by the profile bootstrap when removing `--profile`
+ * or `--alias` would otherwise make the following value-like token become the
+ * value of a preceding optional/extension flag. `parseArgs` ignores it, but its
+ * flag-looking shape preserves argv boundaries during the second parse.
+ */
+export const PROFILE_BOOTSTRAP_BOUNDARY_ARG = "--omp-profile-boundary";
+
+/**
+ * Long-form launch flags that take NO value (booleans). The bootstrap pre-parser
+ * needs this to tell a known value-less flag (whose successor is a fresh
+ * argument — `omp --print --profile work` still selects a profile) apart from an
+ * UNKNOWN long option that might be an extension string flag consuming the next
+ * token as its value (so the bootstrap must not steal that token as a global
+ * `--profile`/`--alias`). MUST mirror the value-less flag arms of `parseArgs`
+ * in `./args.ts`: adding a new boolean launch flag there means adding it here,
+ * or `--<newflag> --profile X` stops selecting a profile. Short aliases
+ * (`-h`/`-v`/`-c`/`-p`) are intentionally omitted — the protection rule only
+ * fires for `--`-prefixed tokens.
+ */
+export const VALUELESS_FLAGS: ReadonlySet<string> = new Set([
+	"--help",
+	"--version",
+	"--allow-home",
+	"--continue",
+	"--no-session",
+	"--no-tools",
+	"--no-lsp",
+	"--no-pty",
+	"--hide-thinking",
+	"--advisor",
+	"--print",
+	"--print-thoughts",
+	"--no-extensions",
+	"--no-skills",
+	"--no-rules",
+	"--no-title",
+	"--auto-approve",
+	"--yolo",
+]);
+
+/**
+ * Whether a bare long option (`--xxx`, no `=`) is unclassified — not a known
+ * string-, optional-, or value-less flag. The bootstrap and subcommand
+ * resolver treat these as possible extension string flags that may consume a
+ * value-like successor (the extension flag table is not yet loaded). Shared so
+ * both call sites classify identically.
+ */
+export function isUnknownLongValueCandidate(arg: string): boolean {
+	return (
+		arg.startsWith("--") &&
+		!arg.includes("=") &&
+		!STRING_VALUE_FLAGS.has(arg) &&
+		!OPTIONAL_VALUE_FLAGS.has(arg) &&
+		!VALUELESS_FLAGS.has(arg)
+	);
+}
+
+/**
+ * Whether a leading option `flag` consumes the following argv token `next` as
+ * its value, applying the same contract as `extractProfileFlags` / `parseArgs`.
+ * Single source of truth so subcommand detection ({@link resolveCliArgv}) skips
+ * a flag's value instead of mistaking it for the subcommand — `omp --model acp`
+ * means model `acp`, not the `acp` subcommand, exactly as the launch parser
+ * reads it.
+ */
+export function flagConsumesValue(flag: string, next: string | undefined): boolean {
+	// `--flag=value` carries its own value inline.
+	if (flag.startsWith("--") && flag.includes("=")) return false;
+	if (next === undefined) return false;
+	// Known string flags consume any successor, even a flag-looking one
+	// (`--system-prompt --foo` ⇒ the system prompt is literally `--foo`).
+	if (STRING_VALUE_FLAGS.has(flag)) return true;
+	const valueLike = !next.startsWith("-");
+	if (EXTENSION_SHADOWABLE_STRING_FLAGS.has(flag)) return valueLike;
+	if (OPTIONAL_VALUE_FLAGS.has(flag)) {
+		const config = OPTIONAL_FLAGS[flag];
+		return valueLike && !(config.rejectEmpty === true && next.length === 0);
+	}
+	if (isUnknownLongValueCandidate(flag)) return valueLike;
+	return false;
+}