Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.
import { open } from "node:fs/promises";
import path from "node:path";
import { decodeInlineEscapes } from "./content-segments.js";
import type {
CommandArguments,
CommandInputReader,
CommandOption,
NormalizedCommandInput,
} from "./command-definition.js";
import { CliError } from "./errors.js";
const byteLimit = 5 * 1024 * 1024;
export function option(
args: CommandArguments,
name: string,
): string | undefined {
const found = args.options[name];
if (found && found.length > 1)
throw new CliError("usage", `Use ${name} at most once.`);
return found?.[0];
}
export function values(
args: CommandArguments,
name: string,
): readonly string[] {
return args.options[name] ?? [];
}
export function requiredOption(args: CommandArguments, name: string): string {
const value = option(args, name);
if (value === undefined) throw new CliError("usage", `Provide ${name}.`);
return value;
}
export function assertPositionals(
args: CommandArguments,
min: number,
max = min,
): void {
if (args.positionals.length < min || args.positionals.length > max)
throw new CliError(
"usage",
"Provide the positional arguments shown in this command's help.",
);
}
export function parseArguments(
args: readonly string[],
definitions: Readonly<Record<string, CommandOption>>,
): CommandArguments {
const options: Record<string, string[]> = Object.create(null);
const positionals: string[] = [];
const ordered: { name: string; value: string }[] = [];
let literal = false;
let stdin = false;
for (let index = 0; index < args.length; index++) {
const token = args[index]!;
if (!literal && token === "--") {
literal = true;
continue;
}
if (literal || !token.startsWith("-")) {
positionals.push(token);
continue;
}
const separator = token.indexOf("=");
const name = separator < 0 ? token : token.slice(0, separator);
const definition = Object.hasOwn(definitions, name)
? definitions[name]
: undefined;
if (!definition)
throw new CliError(
"usage",
`Unknown option: ${name}. Run this command with --help.`,
);
if (options[name] && !definition.repeatable)
throw new CliError("usage", `Use ${name} at most once.`);
if (definition.boolean && separator >= 0)
throw new CliError("usage", `${name} does not take a value.`);
const value = definition.boolean
? "true"
: separator >= 0
? token.slice(separator + 1)
: args[++index];
if (value === undefined)
throw new CliError("usage", `Provide a value after ${name}.`);
if (value.includes("\0"))
throw new CliError("invalid_input", `${name} cannot contain NUL.`);
if (value === "-" && (name === "--file" || name.endsWith("-file"))) {
if (stdin)
throw new CliError("usage", "Only one input source may read stdin.");
stdin = true;
}
(options[name] ??= []).push(value);
ordered.push({ name, value });
}
return { options, positionals, ordered };
}
export function parseJsonValue(text: string): unknown {
if (Buffer.byteLength(text) > byteLimit)
throw new CliError("invalid_input", "JSON input must not exceed 5 MiB.");
let result: unknown;
try {
result = JSON.parse(text);
} catch {
throw new CliError("invalid_input", "Provide one valid JSON value.");
}
// JSON.parse discards duplicate properties. Inspect the validated token stream
// separately so escaped aliases cannot silently replace an earlier value.
const stack: { keys?: Set<string>; expectingKey: boolean }[] = [];
const tokens = text.matchAll(
/"(?:\\.|[^"\\])*"|[{}[\],:]|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null/gu,
);
for (const match of tokens) {
const token = match[0];
if (token === "{" || token === "[") {
if (stack.length >= 100)
throw new CliError(
"invalid_input",
"JSON nesting must not exceed 100 levels.",
);
stack.push({
...(token === "{" ? { keys: new Set<string>() } : {}),
expectingKey: token === "{",
});
} else if (token === "}" || token === "]") stack.pop();
else {
const frame = stack.at(-1);
if (!frame?.keys) continue;
if (token === ",") frame.expectingKey = true;
else if (token === ":") frame.expectingKey = false;
else if (frame.expectingKey && token.startsWith('"')) {
const key = JSON.parse(token) as string;
if (frame.keys.has(key))
throw new CliError(
"invalid_input",
"JSON objects cannot contain duplicate keys.",
);
frame.keys.add(key);
}
}
}
return result;
}
export function createInputReader(dependencies: {
cwd: string;
localPath?: (source: string) => string;
readInput?: (source: string) => Promise<string>;
}): CommandInputReader {
const localPath =
dependencies.localPath ??
((source: string) => path.resolve(dependencies.cwd, source));
let stdinRead = false;
const text = async (source: string): Promise<string> => {
if (!source || source.includes("\0"))
throw new CliError(
"invalid_input",
"Provide a valid input file path or - for stdin.",
);
if (source === "-") {
if (stdinRead)
throw new CliError("usage", "Only one input source may read stdin.");
stdinRead = true;
}
const filename = source === "-" ? "-" : localPath(source);
try {
if (dependencies.readInput) {
const result = await dependencies.readInput(filename);
if (Buffer.byteLength(result) > byteLimit)
throw new CliError("invalid_input", "Input must not exceed 5 MiB.");
return result;
}
let handle;
if (filename !== "-") {
handle = await open(filename, "r");
try {
const stat = await handle.stat();
if (!stat.isFile() || stat.size > byteLimit)
throw new CliError(
"invalid_input",
"Input must be a regular file of at most 5 MiB.",
);
} catch (error) {
await handle.close();
throw error;
}
}
const stream = handle ? handle.createReadStream() : process.stdin;
const chunks: Buffer[] = [];
let size = 0;
try {
for await (const part of stream) {
const chunk = Buffer.isBuffer(part) ? part : Buffer.from(part);
size += chunk.length;
if (size > byteLimit)
throw new CliError("invalid_input", "Input must not exceed 5 MiB.");
chunks.push(chunk);
}
} finally {
if (handle) {
stream.destroy();
await handle.close();
}
}
try {
return new TextDecoder("utf-8", {
fatal: true,
ignoreBOM: true,
}).decode(Buffer.concat(chunks));
} catch {
throw new CliError(
"invalid_input",
"Input must contain valid UTF-8 text.",
);
}
} catch (error) {
if (error instanceof CliError) throw error;
throw new CliError(
"invalid_input",
"Could not read the input file or stdin.",
);
}
};
return {
cwd: dependencies.cwd,
localPath,
text,
json: async (source) => parseJsonValue(await text(source)),
};
}
export async function bodySource(
args: CommandArguments,
reader: CommandInputReader,
required = true,
[inlineFlag, fileFlag]: readonly [string, string] = ["--content", "--file"],
): Promise<string | undefined> {
const content = option(args, inlineFlag);
const file = option(args, fileFlag);
if (content !== undefined && file !== undefined)
throw new CliError(
"usage",
`Choose ${inlineFlag} or ${fileFlag}, not both.`,
);
if (content !== undefined) return content;
if (file !== undefined) return reader.text(file);
if (required)
throw new CliError("usage", `Provide ${inlineFlag} or ${fileFlag}.`);
return undefined;
}
/** Markdown bodies decode \n, \t and \\ in inline --content outside code; files stay literal. */
export async function markdownBodySource(
args: CommandArguments,
reader: CommandInputReader,
required = true,
flags: readonly [string, string] = ["--content", "--file"],
): Promise<string | undefined> {
const body = await bodySource(args, reader, required, flags);
return body !== undefined && option(args, flags[0]) !== undefined
? decodeInlineEscapes(body)
: body;
}
export async function jsonSource(
args: CommandArguments,
reader: CommandInputReader,
inlineFlag: string,
fileFlag: string,
): Promise<unknown> {
const inline = option(args, inlineFlag);
const file = option(args, fileFlag);
if (inline !== undefined && file !== undefined)
throw new CliError(
"usage",
`Choose ${inlineFlag} or ${fileFlag}, not both.`,
);
return inline !== undefined
? parseJsonValue(inline)
: file !== undefined
? reader.json(file)
: undefined;
}
export function targetFromFlags(
args: CommandArguments,
allowedTypes: readonly string[],
): Pick<NormalizedCommandInput, "target"> {
const found = allowedTypes.flatMap((type) => {
const id = option(args, `--${type}`);
return id === undefined ? [] : [{ type, id }];
});
if (found.length > 1)
throw new CliError(
"usage",
`Choose only one target: ${allowedTypes.map((type) => `--${type}`).join(", ")}.`,
);
const target = found[0];
if (!target) return {};
if (
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u.test(target.id) ||
(target.type !== "inbox" &&
/^(?:room|thread|task|meta|taskmeta):/u.test(target.id))
)
throw new CliError(
"usage",
`Provide a bare resource ID after --${target.type}.`,
);
// A target names a resource inside the configured caller Context; it never
// replaces that Context.
return { target };
}