@pmndrs/pine 0.0.0-stage → 0.1.0

package/src/skills.d.ts

@@ -0,0 +1,67 @@
+import { type AgentConfig, type PineConfig } from "./config.ts";
+/**
+ * Skills: what an agent knows how to do, written down. A skill is a folder with a SKILL.md (a
+ * name, a line on when to use it, and the instructions) and whatever files those instructions
+ * refer to. The agent sees name and line in its prompt and reads the rest when a task calls for it.
+ *
+ * Like event sources and MCP servers, a skill is for one conversation, for one agent or for all
+ * agents. Unlike them it needs no entry in a configuration file: where the folder lies says whom
+ * it is for.
+ *
+ *   <home>/skills/<name>/                                 all agents
+ *   <home>/agents/<id>/skills/<name>/                     that agent, in all its conversations
+ *   <home>/agents/<id>/conversations/<session>/skills/<name>/   that one conversation
+ *
+ * All three lie in pine's home, where an agent can read its own but write nothing: a skill is
+ * part of an agent's instructions, and is written by pine when a tool asks for it.
+ */
+export type SkillScope = "local" | "agent" | "global";
+export interface SkillInfo {
+    name: string;
+    description: string;
+    scope: SkillScope;
+    dir: string;
+    /** Put there by pine's tools, so the tools may also replace and remove it. The owner's own folders (`skills` in a configuration file) are not. */
+    managed: boolean;
+}
+export declare const localSkillsDir: (agent: AgentConfig, session: string) => string;
+/** The folders an agent's session reads skills from, beyond what its configuration names. */
+export declare function skillDirs(cfg: PineConfig, agent: AgentConfig, session: string): string[];
+/** The skills one conversation of an agent has, the nearest first: its own, the agent's, those for all agents. */
+export declare function listSkills(cfg: PineConfig, agent: AgentConfig, session: string): SkillInfo[];
+/**
+ * Every skill that one of a scope would stand beside: for a conversation what it sees, for an
+ * agent also what its other conversations have, for all agents everything there is. A name is
+ * used once among those, so that no conversation ever has two skills of one name.
+ */
+export declare function skillsBeside(cfg: PineConfig, agent: AgentConfig, scope: SkillScope, session: string): SkillInfo[];
+/** Every skill there is, with whom it is for: for whoever looks at the whole setup. */
+export declare function allSkills(cfg: PineConfig): Array<SkillInfo & {
+    agent?: string;
+    session?: string;
+}>;
+export interface SkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    /** A folder whose files go along with the skill: scripts, references, templates. */
+    files?: string;
+}
+/** Check what a skill is to be before anybody is asked anything. Returns it tidied, with the files that would be copied. */
+export declare function checkSkill(spec: SkillSpec, workspace: string): SkillSpec & {
+    copy: Array<{
+        from: string;
+        to: string;
+    }>;
+    workspace: string;
+};
+/** Where a skill of a scope lies. */
+export declare function skillDir(cfg: PineConfig, agent: AgentConfig, scope: SkillScope, session: string, name: string): string;
+/** Write a skill, in place of one of the same name in the same place. */
+export declare function writeSkill(dir: string, skill: ReturnType<typeof checkSkill>): void;
+/** Delete a skill's folder, and the folders above it that it leaves empty, up to the agent's or pine's own. */
+export declare function deleteSkill(dir: string, stop: string): void;
+/** A conversation is removed: the skills that were its own go with it. */
+export declare function dropConversationSkills(agent: AgentConfig, session: string): string[];
+/** A conversation got another name: its skills follow it. */
+export declare function renameConversationSkills(agent: AgentConfig, from: string, to: string): void;

package/src/skills.js

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+import { agentSkillsDir, conversationsDir, globalSkillsDir } from "./config.js";
+import { isInside, realish } from "./security.js";
+import { safeName } from "./util.js";
+const MAX_TEXT = 40_000;
+const MAX_FILES = 200;
+const MAX_BYTES = 4 * 1024 * 1024;
+export const localSkillsDir = (agent, session) => path.join(conversationsDir(agent), safeName(session), "skills");
+/** The folders an agent's session reads skills from, beyond what its configuration names. */
+export function skillDirs(cfg, agent, session) {
+    return [globalSkillsDir(cfg), ...(session === "main" ? [] : [localSkillsDir(agent, session)])].filter((d) => fs.existsSync(d));
+}
+const read = (dir, scope, managed) => fs.existsSync(dir) ? loadSkillsFromDir({ dir, source: scope }).skills.map((s) => ({ name: s.name, description: s.description, scope, dir: s.baseDir, managed })) : [];
+/** The skills one conversation of an agent has, the nearest first: its own, the agent's, those for all agents. */
+export function listSkills(cfg, agent, session) {
+    const out = [
+        ...(session === "main" ? [] : read(localSkillsDir(agent, session), "local", true)),
+        ...read(agentSkillsDir(agent), "agent", true),
+        ...agent.skills.flatMap((d) => read(d, "agent", false)),
+        ...read(globalSkillsDir(cfg), "global", true),
+        ...cfg.skills.filter((d) => realish(d) !== realish(globalSkillsDir(cfg))).flatMap((d) => read(d, "global", false)),
+    ];
+    return out.filter((s, i) => out.findIndex((x) => x.name === s.name) === i);
+}
+/**
+ * Every skill that one of a scope would stand beside: for a conversation what it sees, for an
+ * agent also what its other conversations have, for all agents everything there is. A name is
+ * used once among those, so that no conversation ever has two skills of one name.
+ */
+export function skillsBeside(cfg, agent, scope, session) {
+    const locals = (a) => (fs.existsSync(conversationsDir(a)) ? fs.readdirSync(conversationsDir(a)).flatMap((s) => read(path.join(conversationsDir(a), s, "skills"), "local", true)) : []);
+    if (scope === "local")
+        return listSkills(cfg, agent, session);
+    if (scope === "agent")
+        return [...locals(agent), ...listSkills(cfg, agent, "main")];
+    return Object.values(cfg.agents).flatMap((a) => [...locals(a), ...listSkills(cfg, a, "main")]);
+}
+/** Every skill there is, with whom it is for: for whoever looks at the whole setup. */
+export function allSkills(cfg) {
+    const global = [...read(globalSkillsDir(cfg), "global", true), ...cfg.skills.filter((d) => realish(d) !== realish(globalSkillsDir(cfg))).flatMap((d) => read(d, "global", false))];
+    const perAgent = Object.values(cfg.agents).flatMap((a) => [
+        ...[...read(agentSkillsDir(a), "agent", true), ...a.skills.flatMap((d) => read(d, "agent", false))].map((s) => ({ ...s, agent: a.id })),
+        ...(fs.existsSync(conversationsDir(a)) ? fs.readdirSync(conversationsDir(a)) : []).flatMap((session) => read(path.join(conversationsDir(a), session, "skills"), "local", true).map((s) => ({ ...s, agent: a.id, session }))),
+    ]);
+    return [...global, ...perAgent];
+}
+/** Check what a skill is to be before anybody is asked anything. Returns it tidied, with the files that would be copied. */
+export function checkSkill(spec, workspace) {
+    const name = String(spec.name ?? "").trim();
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) || name.length > 64)
+        throw new Error(`"${name}" is not a usable skill name: lowercase letters, digits and single hyphens, at most 64 characters (for example invoices, solar-yield)`);
+    if (name === "pine")
+        throw new Error('"pine" is the name of pine\'s own manual');
+    const description = String(spec.description ?? "").replace(/\s+/g, " ").trim();
+    if (!description)
+        throw new Error(`a skill needs a "description": one or two sentences on what it is for and when to use it. You decide by that line alone whether to read the skill`);
+    if (description.length > 1024)
+        throw new Error(`the description is too long (${description.length} characters, at most 1024). It says when to use the skill; how to do it goes into "instructions"`);
+    const instructions = String(spec.instructions ?? "").trim();
+    if (!instructions)
+        throw new Error(`a skill needs "instructions": what to do, step by step, written to yourself`);
+    if (instructions.length > MAX_TEXT)
+        throw new Error(`the instructions are too long (${instructions.length} characters, at most ${MAX_TEXT}). Put long material into files next to the skill ("files") and refer to them`);
+    const copy = [];
+    if (spec.files) {
+        const root = realish(path.resolve(workspace, spec.files));
+        if (!isInside(realish(workspace), root) || root === realish(workspace))
+            throw new Error(`"files" must be a folder inside your workspace`);
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+            throw new Error(`${root} is not a folder that exists`);
+        let bytes = 0;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const from = path.join(dir, entry.name);
+                // Only what is really there: a link could point at anything.
+                if (entry.isSymbolicLink())
+                    throw new Error(`${from} is a link; a skill carries files, not links`);
+                if (entry.isDirectory()) {
+                    if (entry.name === ".git" || entry.name === "node_modules")
+                        continue;
+                    walk(from);
+                }
+                else if (entry.isFile()) {
+                    const to = path.relative(root, from);
+                    if (to === "SKILL.md")
+                        continue;
+                    bytes += fs.statSync(from).size;
+                    copy.push({ from, to });
+                    if (copy.length > MAX_FILES || bytes > MAX_BYTES)
+                        throw new Error(`${root} is too much for a skill (at most ${MAX_FILES} files and ${MAX_BYTES / 1024 / 1024} MB)`);
+                }
+            }
+        };
+        walk(root);
+    }
+    return { name, description, instructions, copy, workspace: realish(workspace) };
+}
+/** Where a skill of a scope lies. */
+export function skillDir(cfg, agent, scope, session, name) {
+    return path.join(scope === "global" ? globalSkillsDir(cfg) : scope === "agent" ? agentSkillsDir(agent) : localSkillsDir(agent, session), name);
+}
+/** Write a skill, in place of one of the same name in the same place. */
+export function writeSkill(dir, skill) {
+    // Built beside it and swapped in, so that a half-written skill is never read.
+    const fresh = `${dir}.new-${process.pid}`;
+    fs.rmSync(fresh, { recursive: true, force: true });
+    fs.mkdirSync(fresh, { recursive: true, mode: 0o700 });
+    for (const f of skill.copy) {
+        fs.mkdirSync(path.dirname(path.join(fresh, f.to)), { recursive: true });
+        // Between the check and now the owner may have been asked: what is copied is looked at again,
+        // and a file that has since become a link, or leads out of the workspace, is not followed.
+        let fd;
+        try {
+            if (!isInside(skill.workspace, realish(f.from)))
+                throw new Error("it leads out of your workspace");
+            fd = fs.openSync(f.from, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            if (!fs.fstatSync(fd).isFile())
+                throw new Error("it is not a file");
+            fs.writeFileSync(path.join(fresh, f.to), fs.readFileSync(fd));
+        }
+        catch (e) {
+            fs.rmSync(fresh, { recursive: true, force: true });
+            throw new Error(`${f.from} changed while the skill was being added and is not taken: ${e instanceof Error ? e.message : e}`);
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+    }
+    // The description as a quoted string, which is the same in JSON and in YAML: a colon in it cannot break the header.
+    fs.writeFileSync(path.join(fresh, "SKILL.md"), `---\nname: ${skill.name}\ndescription: ${JSON.stringify(skill.description)}\n---\n\n${skill.instructions}\n`);
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.renameSync(fresh, dir);
+}
+/** Delete a skill's folder, and the folders above it that it leaves empty, up to the agent's or pine's own. */
+export function deleteSkill(dir, stop) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    for (let up = path.dirname(dir); isInside(stop, up) && up !== stop; up = path.dirname(up)) {
+        if (!fs.existsSync(up) || fs.readdirSync(up).length)
+            break;
+        fs.rmdirSync(up);
+    }
+}
+/** A conversation is removed: the skills that were its own go with it. */
+export function dropConversationSkills(agent, session) {
+    const dir = localSkillsDir(agent, session);
+    const names = read(dir, "local", true).map((s) => s.name);
+    fs.rmSync(path.dirname(dir), { recursive: true, force: true });
+    if (fs.existsSync(conversationsDir(agent)) && !fs.readdirSync(conversationsDir(agent)).length)
+        fs.rmdirSync(conversationsDir(agent));
+    return names;
+}
+/** A conversation got another name: its skills follow it. */
+export function renameConversationSkills(agent, from, to) {
+    const a = path.dirname(localSkillsDir(agent, from));
+    const b = path.dirname(localSkillsDir(agent, to));
+    if (!fs.existsSync(a))
+        return;
+    fs.rmSync(b, { recursive: true, force: true });
+    fs.renameSync(a, b);
+}

package/src/source-types.d.ts

@@ -0,0 +1,61 @@
+import type { TSchema } from "typebox";
+/** What setting a source up would mean, worked out before anything is written. */
+export interface SourcePlan {
+    /** The options as they go into the configuration: paths resolved, defaults that matter filled in, secrets made. */
+    options: Record<string, unknown>;
+    /** What it will do, in plain words, for the owner's dialog. */
+    does: string[];
+    /** It reaches something new (a folder elsewhere, a network connection, a port), so the owner is asked first. */
+    opens: boolean;
+    /** A folder the agent gets read access to along with the source. */
+    read?: string;
+    /** What the agent should pass on once it is set up (where a device finds its password, for example). */
+    tell?: string;
+    /**
+     * What it reports is the owner speaking, not outside content: the source itself makes sure of
+     * who is on the other end (a Telegram account the owner paired, for example). The owner is told
+     * so before they confirm.
+     */
+    owner?: boolean;
+}
+export interface SourceSetup {
+    /** The name the source will have. */
+    name: string;
+    /** What it is called in events and addresses: its name, or name@agent for an agent's own source. */
+    key: string;
+    /** The agent it is set up by, and that agent's workspace. */
+    agent: string;
+    workspace: string;
+    /** pine's home folder, which no source may point into. */
+    home: string;
+    /** An absolute path for one an agent wrote: ~ is the user's home, anything relative is meant from the workspace. */
+    resolve(p: string): string;
+    /** A fresh secret of `bytes` random bytes, as letters and digits. */
+    random(bytes: number): string;
+    /** The name a secret option gets in pine's .env file, to tell the owner where to find it. */
+    envName(option: string): string;
+}
+export interface SourceType {
+    /** One line: what a source of this type reports and what it is for. */
+    summary: string;
+    /**
+     * Its options as a JSON schema of an object (typebox's Type.Object). Give each property a
+     * description; mark one that is a password or token with `secret: true`, and pine keeps its value
+     * in .env and out of the configuration, the event log and what models see.
+     */
+    options: TSchema;
+    /** Check the options and say what the source would do. Throw for what cannot work. Without it, a set-up is always put to the owner. */
+    plan?(options: Record<string, any>, setup: SourceSetup): SourcePlan;
+    /**
+     * Its "message" events are somebody writing to the agent: the event's `text` is what they
+     * wrote, it reaches the agent as a message rather than as a report, and the agent's answer goes
+     * back through the source.
+     */
+    talks?: boolean;
+    /**
+     * It can also send. One line for the agent on what sending through it does and what to pass,
+     * for example 'a Telegram message to your owner: {"text": "..."}'. The agent's `send` tool
+     * offers every source that says this.
+     */
+    sends?: string;
+}

package/src/source-types.js

@@ -0,0 +1 @@
+export {};

package/src/sources/command.d.ts

@@ -0,0 +1,4 @@
+import type { SourceType } from "../source-types.ts";
+import type { SourceApi } from "../sources.ts";
+export declare const type: SourceType;
+export default function command(source: SourceApi): void;

package/src/sources/command.js

@@ -0,0 +1,77 @@
+import { Type } from "typebox";
+import { parseDuration } from "../util.js";
+import { clip, found, harmless, lineDiff, pattern, shown } from "../watching.js";
+/**
+ * A command, run again and again: reports when what it prints or how it ends changes. For what
+ * only a command can tell: free disk space, a build, a branch that moved, a log, whether a
+ * machine answers.
+ *
+ * options: { run, every?, match?, timeout? }
+ *   run      the command line, run by bash from the workspace of the agent the source belongs to
+ *   every    how often ("1m" by default)
+ *   match    watch only what this regular expression finds in what it prints
+ *   timeout  how long one run may take ("30s" by default)
+ *
+ * event "changed": { command, code, previousCode?, value, previous }         with match
+ *                  { command, code, previousCode?, added, removed, more? }   without
+ *
+ * The command runs in the sandbox of that agent's shell: it reaches what the agent reaches and
+ * nothing else. The first run is the starting point and reports nothing.
+ */
+const MIN = 5000;
+export const type = {
+    summary: "a command run again and again: reports when what it prints, or how it ends (its exit code), changes. For what only a command can tell: free disk space, a build, a branch that moved, a log, whether a machine answers. It runs like a command in your own shell, with the same limits",
+    options: Type.Object({
+        run: Type.String({ description: 'the command line, run by bash from your workspace, e.g. "df -h /" or "git -C ~/dev/app rev-parse origin/main". One that only looks: it runs unattended, again and again' }),
+        every: Type.Optional(Type.String({ description: 'how often to run it, e.g. "1m", "1h". Default "1m", at least "5s"' })),
+        match: Type.Optional(Type.String({ description: 'watch only what this regular expression finds in what it prints (its first group, if it has one), e.g. "([0-9]+)% used". Without it everything it prints counts' })),
+        timeout: Type.Optional(Type.String({ description: 'how long one run may take before it is stopped. Default "30s"' })),
+    }, { additionalProperties: false }),
+    plan(o, setup) {
+        const run = String(o.run ?? "").trim();
+        if (!run)
+            throw new Error(`needs "run": the command line`);
+        if (run.length > 2000)
+            throw new Error("that command line is too long: put it into a script in your workspace and run that");
+        const every = o.every ?? "1m";
+        if (parseDuration(every) < MIN)
+            throw new Error('"every" must be at least "5s"');
+        if (o.timeout && parseDuration(o.timeout) < 1000)
+            throw new Error('"timeout" must be at least "1s"');
+        if (o.match)
+            pattern(o.match);
+        return {
+            options: { ...o, run },
+            does: [`run this command every ${every}, unattended, with the rights of ${setup.agent}'s shell (its sandbox): ${run}`, `report when ${o.match ? `what /${o.match}/ finds in what it prints` : "what it prints"} or its exit code changes`],
+            opens: true,
+            tell: "Its first run is the starting point and reports nothing; from then on only a change does. The sources tool shows how the last run went.",
+        };
+    },
+};
+export default function command(source) {
+    const o = source.options;
+    const run = typeof o.run === "string" ? o.run.trim() : "";
+    if (!run)
+        throw new Error(`needs "run": the command line`);
+    const re = o.match ? pattern(String(o.match)) : undefined;
+    const timeoutMs = parseDuration(o.timeout ?? "30s");
+    source.poll(o.every ?? "1m", async (signal) => {
+        const { code, output } = await source.exec(run, { timeoutMs, signal });
+        const text = output.replace(/\r\n/g, "\n").trimEnd().slice(0, 200_000);
+        if (re) {
+            const value = found(re, text);
+            source.status(`exit ${code}, ${value === null ? "found nothing with the pattern" : `now: ${harmless(value)}`}`);
+            const was = source.changed({ code, value });
+            if (was)
+                source.emit("changed", { command: clip(run, 300), code, value, previous: shown(was.previous.value), ...(was.previous.code !== code ? { previousCode: was.previous.code } : {}) });
+            return;
+        }
+        source.status(`exit ${code}, ${text ? text.split("\n").length : 0} lines`);
+        const was = source.changed({ code, text });
+        if (!was)
+            return;
+        const diff = lineDiff(String(was.previous.text ?? ""), text);
+        if (diff.added.length || diff.removed.length || was.previous.code !== code)
+            source.emit("changed", { command: clip(run, 300), code, ...(was.previous.code !== code ? { previousCode: was.previous.code } : {}), ...diff });
+    });
+}

package/src/sources/folder.d.ts

@@ -0,0 +1,6 @@
+import type { SourceType } from "../source-types.ts";
+import type { SourceApi } from "../sources.ts";
+/** A file name mask ("*.pdf", "*.{png,jpg}", "a?.txt, b*.md") as a test for a file's name. Capitals do not matter. */
+export declare function maskTest(mask: string): RegExp;
+export declare const type: SourceType;
+export default function folder(source: SourceApi): void;

package/src/sources/folder.js

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { isInside, realish } from "../security.js";
+import { parseDuration, resolvePath } from "../util.js";
+/**
+ * A folder: reports every new or changed file once it has stopped growing. For things that drop
+ * files: a scanner, a download folder, an export from another program.
+ *
+ * options: { dir, mask?, pattern?, ignore?, settle?, recursive? }
+ *   dir        the folder to watch (~ and paths relative to the configuration file work)
+ *   mask       only files whose name matches, as in a shell: "*.pdf", "*.{png,jpg}", "report-??.csv";
+ *              several separated by commas
+ *   pattern    only files whose full path matches this regular expression, e.g. "/src/.*\\.ts$"
+ *   ignore     never files whose path matches this one. Default: version control, dependencies and
+ *              editor leftovers (.git, node_modules, .DS_Store, files ending in ~ or .swp, and such)
+ *   settle     how long a file must stay unchanged before it counts as complete (default "1.5s")
+ *   recursive  also watch folders inside it (default true)
+ *
+ * event "added": { path, file, size, images? }   images is set for jpg, png, webp and gif under 10 MB
+ */
+const TYPES = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp", ".gif": "image/gif" };
+/** A file name mask ("*.pdf", "*.{png,jpg}", "a?.txt, b*.md") as a test for a file's name. Capitals do not matter. */
+export function maskTest(mask) {
+    const one = (glob) => glob
+        .trim()
+        .replace(/[.+^$()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\{([^{}]*)\}/g, (_m, list) => `(?:${list.split(",").map((x) => x.trim()).join("|")})`);
+    // Commas separate masks, except inside braces.
+    const parts = mask.split(/,(?![^{]*\})/).map(one).filter(Boolean);
+    return new RegExp(`^(?:${parts.join("|")})$`, "i");
+}
+export const type = {
+    summary: "a folder: reports every new or changed file in it. For a project folder, what a scanner saves, downloads, an export from another program",
+    options: Type.Object({
+        dir: Type.String({ description: "the folder to watch, absolute or starting with ~" }),
+        mask: Type.Optional(Type.String({ description: 'only files whose name matches, as in a shell: "*.pdf", "*.{png,jpg}"; several separated by commas' })),
+        pattern: Type.Optional(Type.String({ description: 'only files whose full path matches this regular expression, for what a mask cannot say, e.g. "/src/.*\\.ts$"' })),
+        ignore: Type.Optional(Type.String({ description: "never files whose path matches this regular expression. Default: version control, dependencies and editor leftovers (.git, node_modules, .DS_Store and such)" })),
+        recursive: Type.Optional(Type.Boolean({ description: "also watch the folders inside it. Default true" })),
+        settle: Type.Optional(Type.String({ description: 'how long a file must stay unchanged before it counts as complete. Default "1.5s"' })),
+    }, { additionalProperties: false }),
+    plan(o, setup) {
+        const dir = setup.resolve(o.dir);
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            throw new Error(`${dir} is not a folder that exists`);
+        // Its own workspace is nothing new; a folder elsewhere is, and reading its files comes with watching it.
+        const own = isInside(realish(setup.workspace), dir);
+        // The workspace usually lies inside pine's home; everything else in there is pine's own.
+        if (!own && (isInside(realish(setup.home), dir) || isInside(dir, realish(setup.home))))
+            throw new Error("pine's own folder cannot be watched");
+        for (const key of ["pattern", "ignore"])
+            if (o[key])
+                new RegExp(o[key]);
+        if (o.mask)
+            maskTest(o.mask);
+        if (o.settle)
+            parseDuration(o.settle);
+        const only = [o.mask ? `files named ${o.mask}` : "", o.pattern ? `paths matching ${o.pattern}` : ""].filter(Boolean).join(", ");
+        return { options: { ...o, dir }, does: [`watch the folder ${dir}${only ? ` (${only})` : ""} for new and changed files`, ...(own ? [] : [`let ${setup.agent} read the files in that folder`])], opens: !own, read: own ? undefined : dir };
+    },
+};
+export default function folder(source) {
+    const o = source.options;
+    if (typeof o.dir !== "string" || !o.dir)
+        throw new Error(`needs "dir": the folder to watch`);
+    const dir = fs.realpathSync(resolvePath(o.dir, source.base));
+    if (!fs.statSync(dir).isDirectory())
+        throw new Error(`${dir} is not a folder`);
+    const pattern = o.pattern ? new RegExp(String(o.pattern), "i") : undefined;
+    const mask = typeof o.mask === "string" && o.mask.trim() ? maskTest(o.mask) : undefined;
+    // What changes all the time in a project folder without anyone having done anything worth a turn.
+    const ignore = new RegExp(typeof o.ignore === "string" ? o.ignore : "(^|/)(\\.git|\\.hg|\\.svn|node_modules|\\.build|DerivedData|__pycache__|\\.venv|\\.DS_Store)(/|$)|(~|\\.swp|\\.tmp|\\.part|\\.crdownload)$", "i");
+    const settleMs = parseDuration(o.settle ?? "1.5s");
+    const pending = new Map();
+    const seen = new Map();
+    source.media(dir);
+    const check = (file, lastSize) => {
+        pending.delete(file);
+        let stat;
+        try {
+            stat = fs.statSync(file);
+            // A link that leads out of the folder is not a file of this folder.
+            if (!stat.isFile() || !fs.realpathSync(file).startsWith(dir + path.sep))
+                return;
+        }
+        catch {
+            return;
+        }
+        if (stat.size !== lastSize || stat.size === 0)
+            return void pending.set(file, setTimeout(() => check(file, stat.size), settleMs));
+        if (seen.get(file) === stat.mtimeMs)
+            return;
+        seen.set(file, stat.mtimeMs);
+        if (seen.size > 5000)
+            for (const k of [...seen.keys()].slice(0, 2500))
+                seen.delete(k);
+        const mimeType = TYPES[path.extname(file).toLowerCase()];
+        source.emit("added", { path: file, file: path.relative(dir, file), size: stat.size, images: mimeType && stat.size < 10 * 1024 * 1024 ? [{ path: file, mimeType }] : undefined });
+    };
+    const watcher = fs.watch(dir, { recursive: o.recursive !== false }, (_type, name) => {
+        if (!name)
+            return;
+        const file = path.join(dir, String(name));
+        if ((pattern && !pattern.test(file)) || (mask && !mask.test(path.basename(file))) || ignore.test(String(name)) || pending.has(file))
+            return;
+        pending.set(file, setTimeout(() => check(file, -1), 200));
+    });
+    source.onStop(() => {
+        watcher.close();
+        pending.forEach((t) => clearTimeout(t));
+    });
+    source.log.info(`watching ${dir}`);
+}

package/src/sources/ftp.d.ts

@@ -0,0 +1,4 @@
+import type { SourceType } from "../source-types.ts";
+import type { SourceApi } from "../sources.ts";
+export declare const type: SourceType;
+export default function ftp(source: SourceApi): Promise<void>;