sideby 0.16.1 → 0.17.0

package/dist/src/core/ask.js

@@ -0,0 +1,365 @@
+import { randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, readdir, rm, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { AI_TASK_KINDS, stripSecrets, taskPrompt } from '../panel/page-logic.js';
+import { checkAttachmentFiles, copyAttachments, MAX_ATTACHMENTS, privateDir, removeOldAttachments, stagedAttachments, takeStaged, } from './attachments.js';
+import { editConfigAsk, editConfigTerminal } from './config.js';
+import { depsFor } from './desktop-app.js';
+import { UserError } from './errors.js';
+import { writeFileAtomic } from './fs-safe.js';
+import { planHandoff } from './handoff.js';
+import { resolvePaths } from './paths.js';
+import { runProbe, spawnProbe } from './probe.js';
+import { askLauncher, askRunCommand, guessTerminal, installedTerminals, launcherProblem, openTerminal, TERMINALS, validateCustomTemplate, } from './terminal.js';
+export async function pickTaskAccount(rt, opts = {}) {
+    const all = (await rt.accounts()).filter((a) => !opts.family || a.family === opts.family);
+    if (opts.account) {
+        const a = await rt.resolve(opts.account);
+        if (opts.family && a.family !== opts.family)
+            throw new UserError('Choose an account of the requested family; run `sideby list`.');
+        if (a.kind === 'api' || (await rt.status(a)).login === 'logged-in')
+            return { account: a };
+        return { reason: 'none-signed-in' };
+    }
+    // A remembered choice may be an API Account; only the automatic pick below skips them.
+    const preferred = all.find((a) => a.ref === rt.config.ask?.account);
+    if (preferred && (preferred.kind === 'api' || (await rt.status(preferred)).login === 'logged-in'))
+        return { account: preferred };
+    if (!all.length)
+        return { reason: 'no-accounts' };
+    const candidates = [];
+    for (const a of all) {
+        if (a.kind !== 'subscription' || (await rt.status(a)).login !== 'logged-in')
+            continue;
+        candidates.push({ ...a, login: 'logged-in', quota: await rt.quota(a, { fetch: 'never' }) });
+    }
+    if (!candidates.length)
+        return { reason: 'none-signed-in' };
+    const plan = planHandoff('', candidates, rt.readContext().now);
+    const account = all.find((a) => a.ref === plan.pick);
+    return account ? { account } : { reason: 'all-full' };
+}
+export async function taskWorkDir(paths = resolvePaths()) {
+    return privateDir(join(paths.stateDir, 'ai'));
+}
+const TASK_TTL_MS = 3600000;
+// Tasks nobody ran (the terminal did not open, the command was not pasted) still hold a prompt: drop them.
+async function removeStaleTasks(dir) {
+    const names = await readdir(dir).catch(() => []);
+    for (const name of names) {
+        if (!/^[a-f0-9]{16}\.json$/.test(name))
+            continue;
+        const file = join(dir, name);
+        try {
+            const s = await lstat(file);
+            if (s.isFile() && s.uid === process.getuid?.() && Date.now() - s.mtimeMs > TASK_TTL_MS)
+                await unlink(file);
+        }
+        catch {
+            // Another process may have consumed it; a leftover is retried next time.
+        }
+    }
+}
+export const newTaskId = () => randomBytes(8).toString('hex');
+export async function writeTask(task, paths = resolvePaths(), id = newTaskId()) {
+    const dir = await privateDir(join(paths.stateDir, 'ask'));
+    await removeStaleTasks(dir);
+    await removeOldAttachments(paths);
+    const where = { home: paths.home, configDir: paths.configDir, stateDir: paths.stateDir };
+    await writeFileAtomic(join(dir, `${id}.json`), JSON.stringify({ ...task, ...where }), 0o600);
+    return id;
+}
+/**
+ * The state folder `ask --run --state-dir` names, accepted only when it and its `ask` folder are real directories the
+ * user owns that nobody else can write (the `ask` folder private, as writeTask makes it). Anything else is refused.
+ */
+export async function taskStateDir(dir) {
+    const refuse = () => new UserError('This task folder is not yours or not private; click again or rerun `sideby ask`.', {
+        code: 'invalid-task',
+    });
+    if (!isAbsolute(dir) || dir.includes('\0'))
+        throw refuse();
+    try {
+        const state = await lstat(dir);
+        const ask = await lstat(join(dir, 'ask'));
+        const uid = process.getuid?.();
+        if (!state.isDirectory() ||
+            !ask.isDirectory() ||
+            state.uid !== uid ||
+            ask.uid !== uid ||
+            (state.mode & 0o022) !== 0 ||
+            (ask.mode & 0o077) !== 0)
+            throw refuse();
+    }
+    catch {
+        throw refuse();
+    }
+    return dir;
+}
+function validAttachments(list) {
+    return (Array.isArray(list) &&
+        list.length <= MAX_ATTACHMENTS &&
+        list.every((a) => typeof a?.path === 'string' && isAbsolute(a.path) && (a.kind === 'image' || a.kind === 'video')));
+}
+/**
+ * The Host arguments `ask --run` adds for a prompt task: `<imageArg>=<path>` per attached image for a Family that
+ * declares `imageArg` (spec §3.28 "附件"), then the prompt, always last. The `=` form keeps one value per option, so a
+ * Host option that takes several values cannot swallow the prompt. An image that is gone, or whose path holds a comma
+ * (a Host taking lists may split it), is left to the path in the prompt.
+ */
+export async function taskHostArgs(rt, task) {
+    const flag = rt.families.get((await rt.resolve(task.account)).family)?.imageArg;
+    const images = [];
+    if (flag)
+        for (const a of task.attachments ?? []) {
+            if (a.kind !== 'image' || a.path.includes(','))
+                continue;
+            if (await lstat(a.path).then((s) => s.isFile(), () => false))
+                images.push(`${flag}=${a.path}`);
+        }
+    return [...images, task.prompt ?? ''];
+}
+/** `env` with the HOME and XDG folders the task was written under, so the Runtime sees what the Panel saw. */
+export function taskEnv(task, env) {
+    if (!task.home || !task.configDir || !task.stateDir)
+        return env;
+    return {
+        ...env,
+        HOME: task.home,
+        XDG_CONFIG_HOME: dirname(task.configDir),
+        XDG_STATE_HOME: dirname(task.stateDir),
+    };
+}
+export async function readTask(id, paths = resolvePaths()) {
+    const invalid = () => new UserError('This task is unavailable or expired; click again or rerun `sideby ask`.', {
+        code: 'invalid-task',
+    });
+    if (!/^[a-f0-9]{16}$/.test(id))
+        throw invalid();
+    const file = join(paths.stateDir, 'ask', `${id}.json`);
+    try {
+        const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const s = await handle.stat();
+            if (!s.isFile() ||
+                s.uid !== process.getuid?.() ||
+                (s.mode & 0o7777) !== 0o600 ||
+                Date.now() - s.mtimeMs > TASK_TTL_MS ||
+                s.size > 1024 * 1024)
+                throw invalid();
+            const task = JSON.parse(await handle.readFile('utf8'));
+            if (!task ||
+                !['prompt', 'login'].includes(task.kind) ||
+                typeof task.account !== 'string' ||
+                typeof task.cwd !== 'string' ||
+                !isAbsolute(task.cwd) ||
+                (task.kind === 'prompt' && typeof task.prompt !== 'string') ||
+                (task.attachments !== undefined && !validAttachments(task.attachments)) ||
+                // Paths are all there or all absent (a task written before they were recorded), and the state folder is the
+                // one the task was read from.
+                !((task.home === undefined && task.configDir === undefined && task.stateDir === undefined) ||
+                    ([task.home, task.configDir, task.stateDir].every((p) => typeof p === 'string' && isAbsolute(p)) &&
+                        task.stateDir === paths.stateDir)))
+                throw invalid();
+            await unlink(file);
+            return task;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        throw invalid();
+    }
+}
+export async function terminals(rt) {
+    const deps = depsFor(rt);
+    // The Utilities folders are added only to the real defaults, so an injected appDirs stays the whole list.
+    const appDirs = deps.appDirs.some((d) => d === '/Applications')
+        ? [...deps.appDirs, '/System/Applications/Utilities', '/Applications/Utilities']
+        : deps.appDirs;
+    const installed = await installedTerminals({
+        home: rt.paths.home,
+        env: rt.env,
+        platform: deps.platform,
+        appDirs,
+    });
+    if (rt.config.terminal?.custom)
+        installed.push({ id: 'custom' });
+    return {
+        installed,
+        preferred: rt.config.terminal?.preferred ?? null,
+        guess: guessTerminal({ preferred: rt.config.terminal?.preferred, env: rt.env, installed }),
+        terminals: TERMINALS.map((t) => ({ ...t, installed: installed.some((i) => i.id === t.id) })),
+    };
+}
+export async function setPreferredTerminal(rt, id) {
+    if (id !== undefined && !TERMINALS.some((t) => t.id === id))
+        throw new UserError(`Unknown terminal ${JSON.stringify(id)}; choose one of ${TERMINALS.map((t) => t.id).join(', ')}. Run \`sideby terminal\` to see which are installed.`, { code: 'unknown-terminal' });
+    if (id === 'custom' && !rt.config.terminal?.custom)
+        throw new UserError("Set the custom command first: `sideby terminal --custom '<program> … {cwd} … {cmd}'`.", { code: 'custom-missing' });
+    const r = await editConfigTerminal(rt.paths.configFile, { preferred: id });
+    rt.config.terminal = r.after;
+}
+/** Saves `terminal.custom` after checking it names a program and both placeholders; selects it too. */
+export async function setCustomTerminal(rt, template) {
+    try {
+        validateCustomTemplate(template);
+    }
+    catch (err) {
+        throw new UserError(err.message, { code: 'custom-invalid' });
+    }
+    const r = await editConfigTerminal(rt.paths.configFile, { custom: template, preferred: 'custom' });
+    rt.config.terminal = r.after;
+}
+/** The attachments a prompt shown before the task exists lists: uploads still staged, the user's files in place. */
+export async function previewAttachments(rt, input) {
+    if (input.uploads?.length)
+        return stagedAttachments(rt.paths, input.uploads);
+    if (input.files?.length)
+        return checkAttachmentFiles(input.files);
+    return [];
+}
+async function takeAttachments(rt, input, taskId) {
+    if (input.uploads?.length)
+        return takeStaged(rt.paths, input.uploads, taskId);
+    if (input.files?.length)
+        return copyAttachments(rt.paths, input.files, taskId);
+    return [];
+}
+export function promptForTask(rt, input, attachments = []) {
+    if (input.task && !AI_TASK_KINDS.includes(input.task))
+        throw new UserError(`Choose a task: ${AI_TASK_KINDS.join(', ')}; rerun \`sideby ask\`.`);
+    let removedSecrets = false;
+    const prompt = taskPrompt({
+        ...input,
+        task: input.task ?? 'free',
+        attachments: attachments.map(({ path, kind }) => ({ path, kind })),
+        lang: input.lang ?? (/^zh/i.test(rt.env.LC_ALL || rt.env.LC_MESSAGES || rt.env.LANG || '') ? 'zh' : 'en'),
+    }, (text) => {
+        const cleaned = stripSecrets(text);
+        removedSecrets ||= cleaned.removed;
+        return cleaned;
+    });
+    return { prompt, removedSecrets };
+}
+const PICK_DETAIL = {
+    'no-accounts': 'No account yet: create one with `sideby new <family> --next`, or paste the prompt into any AI.',
+    'none-signed-in': 'No account is signed in: run `sideby list`, then `sideby login <account>`; or paste the prompt into any AI.',
+    'all-full': 'Every account has used its quota: wait for a reset (`sideby quota`), or paste the prompt into any AI.',
+};
+async function openTask(rt, task, terminal, launcher = askLauncher(), taskId = newTaskId()) {
+    const choices = await terminals(rt);
+    const id = terminal ?? choices.guess.id;
+    if (!TERMINALS.some((t) => t.id === id))
+        throw new UserError(`Unknown terminal; choose one of ${TERMINALS.map((t) => t.id).join(', ')}, or run \`sideby terminal\` to see which are installed.`);
+    await writeTask(task, rt.paths, taskId);
+    const problem = launcherProblem(launcher, rt.paths.stateDir);
+    // An unsafe path cannot go into the command; the user pastes it where sideby is on PATH.
+    const command = askRunCommand(taskId, rt.paths.stateDir, problem?.reason === 'unsafe-path' ? null : launcher);
+    const deps = depsFor(rt);
+    const result = problem ??
+        (await openTerminal(id, {
+            cwd: task.cwd,
+            command,
+            custom: rt.config.terminal?.custom,
+            installed: choices.installed,
+            platform: deps.platform,
+        }, deps.exec));
+    return {
+        schemaVersion: 1,
+        task: taskId,
+        account: task.account,
+        terminal: id,
+        opened: result.ok,
+        command,
+        ...(!result.ok
+            ? {
+                reason: result.reason,
+                detail: 'detail' in result
+                    ? result.detail
+                    : 'This system has no supported terminal launcher; paste the task command into a terminal.',
+            }
+            : {}),
+    };
+}
+export async function startAiTask(rt, input) {
+    // Checks the task before any attachment is moved or copied.
+    promptForTask(rt, input);
+    const taskId = newTaskId();
+    const attachments = await takeAttachments(rt, input, taskId);
+    const { prompt, removedSecrets } = promptForTask(rt, input, attachments);
+    const pick = await pickTaskAccount(rt, input);
+    // Without an account the prompt is copied instead; the saved attachments stay where it says, until the cleanup.
+    if ('reason' in pick)
+        return {
+            schemaVersion: 1,
+            task: null,
+            account: null,
+            terminal: null,
+            opened: false,
+            command: null,
+            prompt,
+            reason: pick.reason,
+            detail: PICK_DETAIL[pick.reason],
+            removedSecrets,
+            attachments,
+        };
+    if (input.remember && input.account && rt.config.ask?.account !== pick.account.ref) {
+        const saved = await editConfigAsk(rt.paths.configFile, pick.account.ref);
+        rt.config.ask = saved.after;
+    }
+    // A terminal the person picked is kept as their preferred one, as `sideby terminal --set` would.
+    if (input.remember && input.terminal && rt.config.terminal?.preferred !== input.terminal)
+        await setPreferredTerminal(rt, input.terminal);
+    const task = {
+        kind: 'prompt',
+        account: pick.account.ref,
+        prompt,
+        cwd: await taskWorkDir(rt.paths),
+    };
+    if (attachments.length)
+        task.attachments = attachments.map(({ path, kind }) => ({ path, kind }));
+    return {
+        ...(await openTask(rt, task, input.terminal, undefined, taskId)),
+        removedSecrets,
+        attachments,
+    };
+}
+export async function openLoginInTerminal(rt, ref) {
+    const account = await rt.resolve(ref);
+    return openTask(rt, { kind: 'login', account: account.ref, cwd: await taskWorkDir(rt.paths) });
+}
+/**
+ * What `try` will run for an Account, computed as `sideby run` would (Family defaults, config arguments) but without
+ * reading its Secret File or running `launch.before` hooks: nothing runs before the user agrees.
+ */
+export async function tryPreview(rt, ref) {
+    const account = await rt.resolve(ref);
+    const family = rt.families.get(account.family);
+    if (!family?.probe)
+        throw new UserError(`This tool cannot be tried; use \`sideby run ${account.ref}\` instead.`, {
+            code: 'no-probe',
+        });
+    const { bin, args } = await rt.launchCommand(account.ref, family.probe.args, 'run');
+    return { account, family, command: [bin, ...args] };
+}
+/**
+ * `sideby try` and the Panel (spec §3.28): runs the Family's probe once the way Launch starts the Host, in a temp
+ * folder under the task directory that is removed afterwards. The caller has already said it spends a few tokens. The
+ * launch is prepared once here, so `launch.before` hooks run once, and the command returned is what actually ran.
+ * `spawn` replaces the process start (tests); by default the Host runs with stdin ignored and is killed at the timeout.
+ */
+export async function tryAccount(rt, ref, spawn = spawnProbe) {
+    const { account, family } = await tryPreview(rt, ref);
+    const launch = await rt.prepareLaunch(account.ref, family.probe.args, 'run');
+    const cwd = await mkdtemp(join(await taskWorkDir(rt.paths), 'probe-'));
+    try {
+        const result = await runProbe(account, { family, baseEnv: rt.env, cwd, launch, spawn });
+        return { account: account.ref, command: [launch.bin, ...launch.args], ...result };
+    }
+    finally {
+        await rm(cwd, { recursive: true, force: true });
+    }
+}

package/dist/src/core/attachments.d.ts

@@ -0,0 +1,50 @@
+import type { Paths } from './paths.ts';
+export type AttachmentKind = 'image' | 'video';
+export interface Attachment {
+    /** Absolute path of the saved file (`--print`: of the user's own file). */
+    path: string;
+    kind: AttachmentKind;
+    bytes: number;
+}
+interface FileType {
+    ext: 'png' | 'jpg' | 'gif' | 'webp' | 'mp4' | 'mov' | 'webm';
+    kind: AttachmentKind;
+    mime: string;
+}
+export declare const ATTACHMENT_LIMITS: Record<AttachmentKind, number>;
+/** The largest upload the Panel accepts; the per-kind limit is checked once the type is known. */
+export declare const MAX_UPLOAD_BYTES: number;
+export declare const MAX_ATTACHMENTS = 5;
+/** What the staging folder holds at most, whatever the browser does: uploads beyond it are refused. */
+export declare const MAX_STAGED_FILES = 20;
+export declare const MAX_STAGED_BYTES: number;
+export declare const SUPPORTED_TYPES = "a PNG, JPEG, GIF or WebP image, or an MP4, MOV or WebM video";
+/** The type of a file from its first bytes, or null when it is none sideby accepts. */
+export declare function sniffType(head: Uint8Array): FileType | null;
+/** A directory the user owns, mode 700; a link or someone else's directory is refused. */
+export declare function privateDir(path: string): Promise<string>;
+/**
+ * `sideby ask --print --attach`: checks the user's files as an upload would be checked and returns them where they
+ * are, since `--print` writes nothing.
+ */
+export declare function checkAttachmentFiles(files: readonly string[]): Promise<Attachment[]>;
+/** `sideby ask --attach`: copies the user's files into the task's attachment folder as `1.png`, `2.mp4`, … */
+export declare function copyAttachments(paths: Pick<Paths, 'stateDir'>, files: readonly string[], taskId: string): Promise<Attachment[]>;
+export declare function stageUpload(paths: Pick<Paths, 'stateDir'>, source: AsyncIterable<Uint8Array>, now?: number): Promise<{
+    id: string;
+    kind: AttachmentKind;
+    bytes: number;
+    mime: string;
+}>;
+/** The staged uploads where they are, for a prompt shown before the task exists. */
+export declare function stagedAttachments(paths: Pick<Paths, 'stateDir'>, ids: readonly string[]): Promise<Attachment[]>;
+/** Deletes staged uploads the person removed before sending; an id that is already gone is skipped. */
+export declare function removeStaged(paths: Pick<Paths, 'stateDir'>, ids: readonly string[]): Promise<number>;
+/** Moves staged uploads into the task's attachment folder, in the order given. */
+export declare function takeStaged(paths: Pick<Paths, 'stateDir'>, ids: readonly string[], taskId: string): Promise<Attachment[]>;
+/**
+ * Drops task attachment folders older than 7 days and staged uploads older than a day; leaves anything else, and
+ * does nothing when a folder on the way is not the user's own real folder.
+ */
+export declare function removeOldAttachments(paths: Pick<Paths, 'stateDir'>, now?: number): Promise<void>;
+export {};