flashlite 0.0.0-stage → 0.1.1

package/dist/images.js

@@ -0,0 +1,84 @@
+// Explicit user-selected local attachments, separate from the agent's confined file tools.
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_ATTACHED_IMAGES = 4;
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+function mediaType(bytes) {
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+        return 'image/jpeg';
+    if (['GIF87a', 'GIF89a'].includes(bytes.subarray(0, 6).toString('ascii')))
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP')
+        return 'image/webp';
+    return undefined;
+}
+export function attachmentPath(value, cwd) {
+    let file = value.trim();
+    if (file.length >= 2 && (file[0] === '"' && file.at(-1) === '"' || file[0] === "'" && file.at(-1) === "'"))
+        file = file.slice(1, -1);
+    else
+        file = file.replace(/\\([\\ '"()])/g, '$1'); // macOS drag-and-drop shell escaping
+    if (!file || file.includes('\0'))
+        throw new Error('provide a local image path');
+    if (file === '~' || file.startsWith('~/'))
+        file = path.join(os.homedir(), file.slice(1));
+    return path.resolve(cwd, file);
+}
+export function imageFromBytes(bytes, name) {
+    if (bytes.length > MAX_IMAGE_BYTES)
+        throw new Error('image exceeds the 10 MiB attachment limit');
+    const type = mediaType(bytes);
+    if (!type)
+        throw new Error('unsupported image — use PNG, JPEG, WebP, or GIF (HEIC is not supported)');
+    return { name: stripVTControlCharacters(path.basename(name)).replace(/[\x00-\x1f\x7f]/g, ' '), mediaType: type, data: bytes.toString('base64') };
+}
+export async function loadImage(value, cwd) {
+    const file = attachmentPath(value, cwd);
+    let handle;
+    try {
+        handle = await fs.open(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch {
+        throw new Error('could not open that image — check the path and file permissions');
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error('attachments must be regular image files');
+        if (stat.size > MAX_IMAGE_BYTES)
+            throw new Error('image exceeds the 10 MiB attachment limit');
+        const chunks = [];
+        let size = 0;
+        while (true) {
+            const buffer = Buffer.alloc(Math.min(64 * 1024, MAX_IMAGE_BYTES + 1 - size));
+            const { bytesRead } = await handle.read(buffer);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > MAX_IMAGE_BYTES)
+                throw new Error('image exceeds the 10 MiB attachment limit');
+            chunks.push(buffer.subarray(0, bytesRead));
+        }
+        return imageFromBytes(Buffer.concat(chunks, size), file);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function imageBytes(image) {
+    return Buffer.byteLength(image.data, 'base64');
+}
+export function addImages(current, added) {
+    const images = [...current, ...added];
+    if (images.length > MAX_ATTACHED_IMAGES)
+        throw new Error('attach at most 4 images per prompt — Ctrl+X clears pending images');
+    if (images.reduce((total, image) => total + imageBytes(image), 0) > MAX_ATTACHMENT_BYTES)
+        throw new Error('attached images exceed the 20 MiB total limit — Ctrl+X clears pending images');
+    return images;
+}

package/dist/index.js

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+// flashlite — a provider-agnostic agentic coding CLI.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RouterClient, errorMessage, dialectFor } from "./client.js";
+import { configPath, migrateConfigFile, normalizeBaseUrl, resolveConfig, saveConfigFile } from "./config.js";
+import { tokenProfile } from "./tokenprofiles.js";
+import { parseApprovalMode } from "./approval.js";
+import { startRepl, runHeadlessAgent } from "./repl.js";
+import { renderMarkdown } from "./markdown.js";
+import { EFFORT_LEVELS, parseEffort } from "./effort.js";
+import { loadImage, addImages } from "./images.js";
+import { listSessions, loadSession, sessionWorkspaceIssue } from "./sessions.js";
+import { textOnlyPrompt } from "./systemprompt.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+function version() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.1.0';
+    }
+}
+function printHelp() {
+    console.log(`flashlite — agentic coding CLI
+
+Usage:
+  flash                     start the REPL
+  flash -p "prompt"         text-only one-shot (no tools or workspace access)
+  flash --agent -p "task"   noninteractive tool workflow; read-only unless explicitly approved
+  flash --check              connectivity + model catalog diagnostic
+  flash --base-url <url>     use another OpenAI-compatible endpoint for this run only
+  flash --set-base-url <url> save the endpoint to config; --reset-base-url clears it
+  flash --resume <id|latest> continue only in its recorded workspace
+  flash --acknowledge-legacy-workspace  acknowledge unknown workspace for legacy --resume
+  flash --model <id>        set the session model
+  flash --effort <level>    auto, low, medium, high, xhigh, max
+  flash --image <path>      attach an image (repeat for more; requires a vision model)
+  flash --absolute          unguarded auto: whole drive + every command; no gate
+  flash --auto              guarded auto: arbitrary commands run; network/installs/sudo/
+                          outside paths/destructive operations still ask
+                          with --agent: denied commands never prompt; not sandboxed
+  flash --auto-approve      allow file changes only; terminal commands still ask/deny
+  flash --mode <m>          start in ask, files, auto, or unguarded
+  flash --debug             print transport metadata only (no raw frames or message content)
+  flash --no-color          plain output
+  flash --version           print the version
+
+Endpoint: set it on first interactive launch, or with --base-url / --set-base-url.
+          Precedence: --base-url > FLASHLITE_BASE_URL > base_url in config.json.
+API key: enter it on first interactive launch; it is saved locally to
+         ~/.config/flashlite/config.json (chmod 600).
+          Your saved API key is sent to whichever endpoint is active.`);
+}
+function parseArgs(argv) {
+    const flags = { check: false, showVersion: false, showHelp: false, images: [], debug: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--check')
+            flags.check = true;
+        else if (arg === '--version' || arg === '-v')
+            flags.showVersion = true;
+        else if (arg === '--help' || arg === '-h')
+            flags.showHelp = true;
+        else if (arg === '--debug')
+            flags.debug = true;
+        else if (arg === '--agent')
+            flags.agent = true;
+        else if (arg === '--acknowledge-legacy-workspace')
+            flags.acknowledgeLegacyWorkspace = true;
+        else if (arg === '--absolute')
+            flags.absoluteMode = true;
+        else if (arg === '--auto')
+            flags.autoMode = true;
+        else if (arg === '--auto-approve')
+            flags.autoApprove = true;
+        else if (arg === '--mode') {
+            const parsed = parseApprovalMode(argv[++i] ?? '');
+            if (!parsed) {
+                console.error('--mode requires ask, files, auto or unguarded.');
+                return null;
+            }
+            flags.mode = parsed;
+        }
+        else if (arg === '--base-url' || arg === '--set-base-url') {
+            const url = normalizeBaseUrl(argv[++i]);
+            if (!url) {
+                console.error(`${arg} requires an http(s) URL without credentials, query or fragment (e.g. https://api.deepseek.com/v1).`);
+                return null;
+            }
+            if (arg === '--base-url')
+                flags.baseUrl = url;
+            else
+                flags.setBaseUrl = url;
+        }
+        else if (arg === '--reset-base-url')
+            flags.resetBaseUrl = true;
+        else if (arg === '--no-color')
+            process.env.NO_COLOR = '1';
+        else if (arg === '--resume') {
+            const id = argv[++i];
+            if (!id || id.startsWith('--')) {
+                console.error('--resume requires a session ID or `latest`');
+                return null;
+            }
+            flags.resume = id;
+        }
+        else if ((arg === '--model' || arg === '-m') && i + 1 < argv.length)
+            flags.model = argv[++i];
+        else if (arg === '--effort') {
+            const effort = parseEffort(argv[++i]);
+            if (!effort) {
+                console.error(`--effort requires one of: ${EFFORT_LEVELS.join(', ')}`);
+                return null;
+            }
+            flags.effort = effort;
+        }
+        else if (arg === '--image') {
+            const file = argv[++i];
+            if (!file || file.startsWith('--')) {
+                console.error('--image requires a local image path');
+                return null;
+            }
+            flags.images.push(file);
+        }
+        else if ((arg === '--prompt' || arg === '-p') && i + 1 < argv.length)
+            flags.prompt = argv[++i];
+        else {
+            if (['--model', '-m', '--prompt', '-p'].includes(arg))
+                console.error(`${arg} requires a value.`);
+            else
+                console.error(`Unknown argument: ${arg}`);
+            console.error('Run `flash --help` for usage.');
+            return null;
+        }
+    }
+    if ([flags.absoluteMode, flags.autoMode, flags.autoApprove, flags.mode].filter(Boolean).length > 1) {
+        console.error('Choose --absolute, --auto, --auto-approve or --mode — not both or multiple.');
+        return null;
+    }
+    if ([flags.baseUrl !== undefined, flags.setBaseUrl !== undefined, flags.resetBaseUrl].filter(Boolean).length > 1) {
+        console.error('Choose one of --base-url, --set-base-url or --reset-base-url.');
+        return null;
+    }
+    return flags;
+}
+function say(line) {
+    process.stdout.write(line + '\n');
+}
+/** Raw-mode line input for first-run setup; masked for secrets, plain for URLs. */
+async function setupLine(prompt, mask, validate) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const input = process.stdin;
+    const wasRaw = input.isRaw;
+    process.stdout.write(prompt);
+    input.setRawMode(true);
+    input.resume();
+    process.stdout.write('\x1b[?25l');
+    return await new Promise((resolve) => {
+        let value = '';
+        const finish = (result) => {
+            input.off('data', onData);
+            input.setRawMode(wasRaw ?? false);
+            process.stdout.write('\x1b[?25h\n');
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString('utf8')) {
+                if (char === '\u0003' || char === '\u001b') {
+                    finish(null);
+                    return;
+                }
+                if (char === '\r' || char === '\n') {
+                    const problem = validate(value);
+                    if (problem) {
+                        process.stdout.write(`\n  ${problem} `);
+                        value = '';
+                        continue;
+                    }
+                    finish(value.trim());
+                    return;
+                }
+                if (char === '\u007f' || char === '\b') {
+                    if (value.length) {
+                        value = value.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                }
+                else if (char >= ' ' && char !== '\u007f' && value.length < 4096) {
+                    value += char;
+                    process.stdout.write(mask ? '*' : char);
+                }
+            }
+        };
+        input.on('data', onData);
+    });
+}
+/** Ask for the OpenAI-compatible endpoint root on first run; returns null if cancelled. */
+async function setupEndpoint() {
+    const value = await setupLine('\n  Endpoint URL (OpenAI-compatible root, e.g. https://api.openai.com/v1): ', false, (v) => (v.trim() ? (normalizeBaseUrl(v) ? null : 'Enter an http(s) URL without credentials, query or fragment:') : 'Endpoint cannot be blank:'));
+    return value ? normalizeBaseUrl(value) : null;
+}
+async function setupApiKey(host) {
+    const value = await setupLine(`\n  Welcome to flashlite\n  Connect your own API key for ${host}. It is saved only in your local config (mode 600).\n\n  API key: `, true, (v) => (v.trim() ? null : 'API key cannot be blank. Try again:'));
+    if (value)
+        process.stdout.write('\n  Saving key locally…');
+    return value;
+}
+async function runCheck(client, config) {
+    const source = config.baseUrlSource && config.baseUrlSource !== 'config' ? ` (${config.baseUrlSource})` : '';
+    say(`base:    ${config.baseUrl}${source}`);
+    try {
+        const models = await client.listModels();
+        say(`models:  ${models.length} in catalog`);
+        for (const m of models.slice(0, 5)) {
+            const ctx = m.contextLength ? ` (${m.contextLength.toLocaleString()} ctx)` : '';
+            say(`  - ${m.id}${ctx}`);
+        }
+        if (models.length > 5)
+            say('  …');
+    }
+    catch (err) {
+        const e = err;
+        say(`models:  FAILED (${e.status ?? '?'}) ${errorMessage(err)}`);
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Session model: --model flag > config default > first-run bootstrap.
+ * The bootstrap prefers the model verified to work on this key, then the first catalog
+ * entry, and persists the choice — never a hardcoded guess.
+ */
+async function resolveSessionModel(flagsModel, config, client) {
+    if (flagsModel)
+        return flagsModel;
+    if (config.defaultModel)
+        return config.defaultModel;
+    let catalog;
+    try {
+        catalog = await client.listModels();
+    }
+    catch (err) {
+        throw new Error('No default model configured and the catalog fetch failed — pass --model <id>. ' +
+            `(${errorMessage(err)})`);
+    }
+    const pick = catalog[0]?.id;
+    if (!pick)
+        throw new Error('The catalog is empty — pass --model <id>.');
+    saveConfigFile({ default_model: pick });
+    return pick;
+}
+async function runOneShot(client, config, model, prompt, images) {
+    const messages = [{ role: 'user', content: prompt, ...(images.length ? { images } : {}) }];
+    const req = {
+        model,
+        dialect: dialectFor(model),
+        messages,
+        system: textOnlyPrompt(),
+        stream: false,
+        maxTokens: tokenProfile(config, config.tokenSaver ?? 'off', config.boostMode ?? false).maxOutputTokens,
+        effort: config.reasoningEffort,
+    };
+    try {
+        const turn = await client.complete(req);
+        const content = turn.message.content || '(no response)';
+        say(renderMarkdown(content).replace(/\n+$/, ''));
+        if (turn.stopReason === 'length')
+            say('! response truncated — consider a shorter scope');
+        return 0;
+    }
+    catch (err) {
+        say('× ' + errorMessage(err));
+        return 1;
+    }
+}
+async function main() {
+    const flags = parseArgs(process.argv.slice(2));
+    if (!flags)
+        return 2;
+    if (flags.showVersion) {
+        console.log(version());
+        return 0;
+    }
+    if (flags.showHelp) {
+        printHelp();
+        return 0;
+    }
+    if (flags.setBaseUrl !== undefined || flags.resetBaseUrl) {
+        if (flags.prompt !== undefined || flags.check || flags.agent || flags.resume) {
+            console.error('--set-base-url and --reset-base-url only save the endpoint; do not combine them with -p, --agent, --check or --resume.');
+            return 2;
+        }
+        if (flags.resetBaseUrl) {
+            saveConfigFile({ base_url: '', default_model: null });
+            say('endpoint cleared — the next launch will ask for one');
+            return 0;
+        }
+        const url = flags.setBaseUrl;
+        const current = resolveConfig().config.baseUrl;
+        const hostChanged = !current || new URL(url).host !== new URL(current).host;
+        saveConfigFile(hostChanged ? { base_url: url, default_model: null } : { base_url: url });
+        say(`endpoint saved: ${url}`);
+        if (hostChanged)
+            console.error('! default model cleared — the new endpoint serves different models; the next launch picks one from its catalog (or pass --model).');
+        console.error('! your saved API key is sent to this endpoint — make sure the key in config.json is valid there.');
+        return 0;
+    }
+    if (flags.agent && (flags.prompt === undefined || flags.check || flags.resume)) {
+        console.error('--agent requires -p/--prompt and cannot be combined with --check or --resume.');
+        return 2;
+    }
+    if (flags.prompt !== undefined && !flags.agent && (flags.autoMode || flags.autoApprove || flags.mode)) {
+        console.error('-p is text-only: permission flags require --agent -p for a tool workflow.');
+        return 2;
+    }
+    if (flags.acknowledgeLegacyWorkspace && !flags.resume) {
+        console.error('--acknowledge-legacy-workspace requires --resume; it never retargets a known workspace.');
+        return 2;
+    }
+    const wantsAbsolute = flags.absoluteMode || flags.mode === 'absolute';
+    if (wantsAbsolute && (flags.prompt !== undefined || flags.check || !process.stdin.isTTY || !process.stdout.isTTY)) {
+        console.error('unguarded auto requires an interactive REPL; not -p or --check.');
+        return 2;
+    }
+    if (flags.resume && (flags.prompt !== undefined || flags.check || wantsAbsolute)) {
+        console.error('--resume is for the interactive REPL and cannot be combined with -p, --check or unguarded auto.');
+        return 2;
+    }
+    if (flags.check && flags.images.length) {
+        console.error('--image is for prompts, not --check');
+        return 2;
+    }
+    let resumed;
+    if (flags.resume) {
+        const id = flags.resume === 'latest' ? listSessions()[0]?.id : flags.resume;
+        if (!id) {
+            console.error('No saved sessions to resume.');
+            return 1;
+        }
+        try {
+            resumed = loadSession(id) ?? undefined;
+        }
+        catch {
+            resumed = undefined;
+        }
+        if (!resumed) {
+            console.error('Could not resume that session. Use `flash --resume latest` to see the most recent valid session.');
+            return 1;
+        }
+        const issue = sessionWorkspaceIssue(resumed.summary);
+        if (issue && issue !== 'legacy') {
+            console.error(issue);
+            return 1;
+        }
+        if (issue === 'legacy') {
+            if (!flags.acknowledgeLegacyWorkspace) {
+                console.error('Legacy session has no workspace identity; it may refer to another directory. Review its origin, then explicitly use --acknowledge-legacy-workspace with --resume to continue here. No permissions are restored.');
+                return 1;
+            }
+            console.error('! acknowledged legacy session with unknown workspace · continuing in the current directory; no permissions restored');
+        }
+    }
+    let images = [];
+    try {
+        for (const file of flags.images)
+            images = addImages(images, [await loadImage(file, process.cwd())]);
+    }
+    catch (err) {
+        console.error('× ' + errorMessage(err));
+        return 2;
+    }
+    for (const note of migrateConfigFile())
+        console.error('! ' + note);
+    const { config, warnings } = resolveConfig(flags.baseUrl);
+    if (flags.effort)
+        config.reasoningEffort = flags.effort;
+    for (const w of warnings)
+        console.error('! ' + w);
+    if (config.baseUrlSource === 'flag') {
+        console.error(`! endpoint ${new URL(config.baseUrl).host} — your saved API key will be sent there`);
+    }
+    if (!config.baseUrl) {
+        if (flags.prompt !== undefined || flags.check || !process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error('No API endpoint configured. Pass --base-url <url> or start `flash` in a terminal to set one.');
+            return 1;
+        }
+        const endpoint = await setupEndpoint();
+        if (!endpoint) {
+            console.error('Setup cancelled. Run `flash` again to configure an endpoint.');
+            return 1;
+        }
+        saveConfigFile({ base_url: endpoint });
+        config.baseUrl = endpoint;
+        config.baseUrlSource = 'config';
+        config.configPath = configPath();
+    }
+    if (!config.apiKey) {
+        if (flags.prompt !== undefined || flags.check || !process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error('No API key found. Start `flash` in a terminal to configure one.');
+            return 1;
+        }
+        const key = await setupApiKey(new URL(config.baseUrl).host);
+        if (!key) {
+            console.error('Setup cancelled. Run `flash` again to configure your API key.');
+            return 1;
+        }
+        saveConfigFile({ api_key: key });
+        config.apiKey = key;
+        config.configPath = configPath();
+    }
+    const client = new RouterClient({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        promptCaching: config.promptCaching,
+        debug: flags.debug ? (line) => console.error('[debug] ' + line) : undefined,
+    });
+    if (flags.check)
+        return await runCheck(client, config);
+    const model = await resolveSessionModel(flags.model ?? resumed?.summary.model, config, client);
+    if (flags.prompt !== undefined && flags.agent) {
+        const abort = new AbortController();
+        const stop = () => abort.abort();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            const outcome = await runHeadlessAgent({
+                client, config, model, prompt: flags.prompt, images,
+                autoMode: flags.autoMode, autoApprove: flags.autoApprove, signal: abort.signal,
+                warn: (notice) => console.error('! ' + notice),
+            });
+            const answer = outcome.history.findLast((message) => message.role === 'assistant' && !message.toolCalls?.length)?.content;
+            if (answer)
+                say(renderMarkdown(answer).replace(/\n+$/, ''));
+            if (outcome.error)
+                console.error('× ' + outcome.error);
+            return outcome.exitCode;
+        }
+        finally {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+        }
+    }
+    if (flags.prompt !== undefined) {
+        return await runOneShot(client, config, model, flags.prompt, images);
+    }
+    startRepl({ client, config, model, images, resume: resumed, legacyWorkspaceAcknowledged: flags.acknowledgeLegacyWorkspace, autoApprove: flags.autoApprove, autoMode: flags.autoMode, absoluteMode: flags.absoluteMode, mode: flags.mode });
+    return 0;
+}
+try {
+    process.exitCode = await main();
+}
+catch (err) {
+    console.error('× ' + errorMessage(err));
+    process.exitCode = 1;
+}