bridgerator 1.0.8 → 1.1.0

package/src/queue.mjs

@@ -0,0 +1,194 @@
+// Task queue (checklist) on this PC: the person adds steps in the Bridgerator window, ChatGPT works
+// through them with the queue_* tools. Stored only here (%APPDATA%\Bridgerator\queue.json, inside
+// the always-excluded folder); never sent to the server. Tools read/write only this list.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { writeAtomic } from './confirm.mjs';
+
+export const STATUSES = ['todo', 'doing', 'done', 'failed', 'skipped'];
+const MAX_ITEMS = 500, MAX_TITLE = 200, MAX_DETAILS = 4000, MAX_NOTE = 1000, MAX_PATHS = 20;
+const RULE = 'The usual loop: queue_next, do the task, queue_update with done / failed / skipped and a short note, then the next one until the queue is empty or the person stops. resultPath set: write the result to that file. from set: another AI added it and reads queue_list.';
+const MAX_FROM = 80, MAX_RESULT_PATH = 1000;
+export const STALE_MS = 30 * 60 * 1000;   // "doing" with no update for this long: another chat gave up
+const ID = { type: 'string', description: 'item id' };
+const STR = (n) => ({ type: 'string', maxLength: n });
+const PATHS = { type: 'array', maxItems: MAX_PATHS, items: STR(1000) };
+// AI ↔ AI hand-off (another AI adds tasks for ChatGPT): who added it, and the file for the result. Optional; old items have neither.
+const HANDOFF = { from: { type: 'string', maxLength: MAX_FROM, description: 'Who adds the task when another AI hands work over, e.g. "Claude Code".' }, resultPath: { type: 'string', maxLength: MAX_RESULT_PATH, description: 'Full path of the file where the result should be written.' } };
+
+export const QUEUE_TOOL_DEFS = [
+  { name: 'queue_list', description: `List the task queue the person keeps on this PC (a checklist of things to do): counts and items (id, title, status, note, worker, updatedAt, from, resultPath), optionally only one status.`, inputSchema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: STATUSES } } } },
+  { name: 'queue_next', description: `Take the next item of the task queue: returns the first "todo" item and marks it "doing" (nothing when the queue is empty). An item left "doing" for 30 minutes without an update (another chat stopped) is returned first, with resumed: true. Several chats can work through one queue at once; each call gets a different item. Pass worker = a short name for this chat (e.g. its title) so the person sees who is on it. ${RULE}`, inputSchema: { type: 'object', additionalProperties: false, properties: { worker: STR(80) } } },
+  { name: 'queue_update', description: `Set an item's status (doing / done / failed / skipped / todo) with a short result note.`, inputSchema: { type: 'object', additionalProperties: false, required: ['id', 'status'], properties: { id: ID, status: { type: 'string', enum: STATUSES }, note: STR(MAX_NOTE) } } },
+  { name: 'queue_add', description: `Add steps to the task queue (e.g. when planning a bigger job with the person): one { title, details?, paths?, from?, resultPath? } or items: [...] (1–100). Another AI handing work to ChatGPT sets from (its name) and resultPath (a file for the result), then reads the outcome with queue_list.`, inputSchema: { type: 'object', additionalProperties: false, properties: { title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, ...HANDOFF, items: { type: 'array', minItems: 1, maxItems: 100, items: { type: 'object', additionalProperties: false, required: ['title'], properties: { title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, ...HANDOFF } } } } } },
+  { name: 'queue_clear', description: 'Remove finished items from the task queue: status done, failed or skipped. status "all" removes every item and needs the person\'s OK on the PC.', inputSchema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: ['done', 'failed', 'skipped', 'all'] } } } },
+  { name: 'queue_edit', description: 'Change the title, details, paths or result file of a queue item.', inputSchema: { type: 'object', additionalProperties: false, required: ['id'], properties: { id: ID, title: STR(MAX_TITLE), details: STR(MAX_DETAILS), paths: PATHS, resultPath: HANDOFF.resultPath } } },
+  { name: 'queue_reorder', description: 'Put queue items in a new order: ids first, in this order; the rest keep their order after them.', inputSchema: { type: 'object', additionalProperties: false, required: ['ids'], properties: { ids: { type: 'array', maxItems: MAX_ITEMS, items: ID } } } },
+];
+export const QUEUE_TOOL_NAMES = new Set(QUEUE_TOOL_DEFS.map((t) => t.name));
+
+const str = (v, n, name, required) => {
+  if (v === undefined || v === null) { if (required) throw new Error(`${name} is required`); return undefined; }
+  if (typeof v !== 'string') throw new Error(`${name} must be text`);
+  const t = v.trim();
+  if (required && !t) throw new Error(`${name} is required`);
+  if (t.length > n) throw new Error(`${name} is longer than ${n} characters`);
+  return t;
+};
+const paths = (v) => {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v) || v.length > MAX_PATHS || v.some((p) => typeof p !== 'string' || p.length > 1000)) throw new Error(`paths must be a list of at most ${MAX_PATHS} paths`);
+  return v.map((p) => p.trim()).filter(Boolean);
+};
+const fromOf = (v) => { const t = str(v, MAX_FROM, 'from'); if (t && /[\u0000-\u001f]/.test(t)) throw new Error('from must be a short name on one line'); return t || undefined; };
+const resultPathOf = (v) => { const t = str(v, MAX_RESULT_PATH, 'resultPath'); if (t && !/^[a-z]:[\\/]/i.test(t)) throw new Error('resultPath must be a full path like C:\\Users\\Name\\Documents\\result.md'); return t || undefined; };
+const handoff = (x) => { const f = fromOf(x?.from), r = resultPathOf(x?.resultPath); return { ...(f ? { from: f } : {}), ...(r ? { resultPath: r } : {}) }; };
+
+export function createQueue(file, { now = () => new Date().toISOString(), onChange = () => {} } = {}) {
+  let items = [], unreadable = null;
+  // Missing file = empty queue. A file that can't be READ (locked, no access) is never overwritten: saves
+  // fail until a restart reads it. A file that can't be PARSED — or has the wrong shape, or items that
+  // are dropped (no id / title, unknown status) — is kept as queue.json.broken-<content hash> before any
+  // save: once per distinct broken content (the same file at every start is not copied again).
+  let raw = null;
+  const keepCopy = () => {
+    const copy = `${file}.broken-${crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)}`;
+    try { fs.copyFileSync(file, copy, fs.constants.COPYFILE_EXCL); } catch (e) { if (e.code !== 'EEXIST') unreadable = 'BROKEN'; }
+  };
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') unreadable = e.code || e.message; }
+  if (raw !== null) {
+    try {
+      const j = JSON.parse(raw.replace(/^/, ''));
+      if (Array.isArray(j?.items)) {
+        items = j.items.filter((x) => x && typeof x === 'object' && typeof x.id === 'string' && x.id && typeof x.title === 'string' && STATUSES.includes(x.status))
+          .map((x, i) => ({ ...x, order: Number.isFinite(x.order) ? x.order : i + 1 }));
+        if (items.length !== j.items.length) keepCopy();
+      } else keepCopy();
+    } catch { keepCopy(); }
+  }
+  // Atomic: write a temp file, then rename over queue.json — a crash or a parallel write never leaves
+  // half a file. (Calls run in one process, so the read-modify-write steps never interleave.)
+  const save = () => {
+    if (unreadable) throw new Error(`queue.json could not be read (${unreadable}); restart Bridgerator to load it — nothing was changed`);
+    if (deferSave) return;
+    writeAtomic(file, JSON.stringify({ items }, null, 2)); onChange();
+  };
+  // Every change is all or nothing: a validation or save error leaves the queue as it was.
+  const commit = (fn) => {
+    const before = structuredClone(items);
+    try { return fn(); } catch (e) { items = before; throw e; }
+  };
+  // Several items in one change: ONE save at the end (a failure half-way leaves queue.json as it was).
+  let deferSave = false;
+  const many = (fn) => commit(() => { deferSave = true; let r; try { r = fn(); } finally { deferSave = false; } save(); return r; });
+  const sorted = () => [...items].sort((a, b) => a.order - b.order);
+  const get = (id) => { const it = items.find((x) => x.id === id); if (!it) throw new Error(`no queue item ${id}`); return it; };
+  const renumber = (list) => list.forEach((x, i) => { x.order = i + 1; });
+
+  return {
+    list: (status) => {
+      if (status !== undefined && !STATUSES.includes(status)) throw new Error(`status must be one of ${STATUSES.join(', ')}`);
+      return sorted().filter((x) => !status || x.status === status);
+    },
+    counts: () => Object.fromEntries(STATUSES.map((s) => [s, items.filter((x) => x.status === s).length])),
+    add(x = {}) { return commit(() => this.add0(x)); },
+    add0({ title, details, paths: p, from, resultPath } = {}) {
+      if (items.length >= MAX_ITEMS) throw new Error(`the queue is full (${MAX_ITEMS} items)`);
+      const t = now();
+      const it = { id: crypto.randomUUID().slice(0, 8), title: str(title, MAX_TITLE, 'title', true), ...(details !== undefined ? { details: str(details, MAX_DETAILS, 'details') } : {}), ...(p !== undefined ? { paths: paths(p) } : {}), ...handoff({ from, resultPath }), status: 'todo', order: (Math.max(0, ...items.map((x) => x.order)) + 1), createdAt: t, updatedAt: t };
+      items.push(it); save(); return it;
+    },
+    // Synchronous take: parallel chats calling queue_next never get the same item.
+    next({ worker } = {}) { return commit(() => {
+      const w = str(worker, 80, 'worker');
+      const t = Date.parse(now());
+      const stale = sorted().find((x) => x.status === 'doing' && t - Date.parse(x.updatedAt) >= STALE_MS);
+      const it = stale || sorted().find((x) => x.status === 'todo');
+      if (!it) return null;
+      if (stale) it.resumedFrom = it.worker || 'another chat';
+      it.status = 'doing'; it.updatedAt = now();
+      if (w) it.worker = w; else delete it.worker;
+      save(); return stale ? { ...it, resumed: true } : it;
+    }); },
+    update({ id, status, note } = {}) { return commit(() => {
+      const it = get(str(id, 40, 'id', true));
+      if (!STATUSES.includes(status)) throw new Error(`status must be one of ${STATUSES.join(', ')}`);
+      const n = note !== undefined ? str(note, MAX_NOTE, 'note') : undefined;
+      it.status = status; it.updatedAt = now();
+      if (note !== undefined) it.note = n;
+      if (['done', 'failed', 'skipped'].includes(status)) it.doneAt = it.updatedAt; else delete it.doneAt;
+      if (status !== 'doing') delete it.worker;
+      save(); return it;
+    }); },
+    edit({ id, title, details, paths: p, resultPath } = {}) { return commit(() => {
+      const it = get(str(id, 40, 'id', true));
+      // Everything is checked first, then changed.
+      const t = title !== undefined ? str(title, MAX_TITLE, 'title', true) : undefined;
+      const d = details !== undefined ? str(details, MAX_DETAILS, 'details') : undefined;
+      const ps = p !== undefined ? paths(p) : undefined;
+      const r = resultPath !== undefined ? resultPathOf(resultPath) : undefined;
+      if (title !== undefined) it.title = t;
+      if (details !== undefined) it.details = d;
+      if (p !== undefined) it.paths = ps;
+      if (resultPath !== undefined) { if (r) it.resultPath = r; else delete it.resultPath; }
+      it.updatedAt = now(); save(); return it;
+    }); },
+    reorder({ ids } = {}) { return commit(() => {
+      if (!Array.isArray(ids)) throw new Error('ids must be a list');
+      const first = ids.map((id) => get(String(id)));
+      renumber([...new Set(first), ...sorted().filter((x) => !first.includes(x))]);
+      save(); return sorted();
+    }); },
+    remove({ id } = {}) { return commit(() => { const it = get(String(id)); items = items.filter((x) => x !== it); renumber(sorted()); save(); return it; }); },
+    // Undo of a delete in the window: the item goes back at its old place.
+    restore(x = {}) { return commit(() => this.restore0(x)); },
+    restore0({ item } = {}) {
+      if (!item || typeof item !== 'object' || typeof item.id !== 'string' || items.some((x) => x.id === item.id)) throw new Error('nothing to restore');
+      if (!STATUSES.includes(item.status)) throw new Error('bad item');
+      const it = { ...item, title: str(item.title, MAX_TITLE, 'title', true) };
+      const list = sorted(); list.splice(Math.max(0, Math.min(list.length, (Number(item.order) || 1) - 1)), 0, it);
+      items = list; renumber(items); save(); return it;
+    },
+    clearFinished() { return commit(() => { items = items.filter((x) => !['done', 'failed', 'skipped'].includes(x.status)); renumber(sorted()); save(); return true; }); },
+    // status: done | failed | skipped | finished (all three) | all → the removed items (for Undo).
+    clear({ status = 'finished' } = {}) {
+      const pick = { done: ['done'], failed: ['failed'], skipped: ['skipped'], finished: ['done', 'failed', 'skipped'], 'failed+skipped': ['failed', 'skipped'], all: STATUSES }[status];
+      if (!pick) throw new Error('status must be done, failed, skipped or all');
+      return commit(() => {
+        const gone = sorted().filter((x) => pick.includes(x.status));
+        items = items.filter((x) => !gone.includes(x)); renumber(sorted()); save();
+        return gone;
+      });
+    },
+    restoreMany({ items: list } = {}) {
+      if (!Array.isArray(list)) throw new Error('nothing to restore');
+      return many(() => { for (const it of [...list].sort((a, b) => a.order - b.order)) this.restore0({ item: it }); return sorted(); });
+    },
+    addMany(list) {
+      if (!Array.isArray(list) || !list.length || list.length > 100) throw new Error('items must be a list of 1–100 tasks');
+      if (items.length + list.length > MAX_ITEMS) throw new Error(`the queue would be over ${MAX_ITEMS} items`);
+      // All or nothing: a half-added list would be added twice when the chat retries.
+      list.forEach((x, i) => { str(x?.title, MAX_TITLE, `items[${i}].title`, true); str(x?.details, MAX_DETAILS, `items[${i}].details`); paths(x?.paths); try { handoff(x); } catch (e) { throw new Error(`items[${i}]: ${e.message}`); } });
+      return many(() => list.map((x) => this.add0(x)));
+    },
+  };
+}
+
+/** queue_* tool call → MCP result. */
+export function queueTool(q, name, args = {}) {
+  const ok = (v) => ({ content: [{ type: 'text', text: JSON.stringify(v, null, 2) }] });
+  try {
+    switch (name) {
+      case 'queue_list': return ok({ counts: q.counts(), items: q.list(args.status).map(({ id, title, status, note, worker, updatedAt, details, paths, from, resultPath }) => ({ id, title, status, ...(note ? { note } : {}), ...(worker ? { worker } : {}), updatedAt, ...(details ? { details } : {}), ...(paths ? { paths } : {}), ...(from ? { from } : {}), ...(resultPath ? { resultPath } : {}) })) });
+      case 'queue_next': { const it = q.next(args); return ok(it ? { item: it } : { item: null, message: 'The queue is empty — tell the person and stop.' }); }
+      case 'queue_update': return ok({ item: q.update(args) });
+      case 'queue_add': return args.items ? ok({ items: q.addMany(args.items) }) : ok({ item: q.add(args) });
+      case 'queue_clear': { if (args.status === 'all') throw new Error('clearing every item needs the person\'s OK'); const gone = q.clear({ status: args.status || 'finished' }); return ok({ removed: gone.length, counts: q.counts() }); }
+      case 'queue_edit': return ok({ item: q.edit(args) });
+      case 'queue_reorder': return ok({ items: q.reorder(args) });
+      default: return { content: [{ type: 'text', text: `unknown queue tool ${name}` }], isError: true };
+    }
+  } catch (e) {
+    return { content: [{ type: 'text', text: `Queue: ${e.message}` }], isError: true };
+  }
+}

package/src/recent.mjs

@@ -0,0 +1,48 @@
+// "Recent on this PC": the last 100 tool calls WITH their command / path, for the person at the PC.
+// In memory; with "Keep a local history" on also in %APPDATA%\Bridgerator\recent.jsonl (inside the
+// always-excluded folder), entries older than 7 days dropped. Never sent to the server.
+import fs from 'node:fs';
+
+export const KEEP = 100;
+export const DAYS = 7;
+const short = (s, n = 300) => { s = String(s ?? ''); return s.length > n ? `${s.slice(0, n - 1)}…` : s; };
+
+export function target(a = {}) {
+  if (!a || typeof a !== 'object') return '';
+  if (a.source && a.destination) return short(`${a.source} → ${a.destination}`);
+  const t = a.command ?? a.input ?? a.path ?? a.file_path ?? (Array.isArray(a.paths) ? a.paths.join(', ') : undefined) ?? a.pattern ?? a.title ?? a.id;
+  return t === undefined ? '' : short(typeof t === 'string' ? t : JSON.stringify(t));
+}
+
+export function createRecent(file, { keepFile = false, now = Date.now } = {}) {
+  let list = [], keep = keepFile;
+  const fresh = (e) => now() - e.t < DAYS * 86400000;
+  const prune = () => {
+    if (!keep) return;
+    try {
+      const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+      const ok = lines.filter((l) => { try { return fresh(JSON.parse(l)); } catch { return false; } });
+      if (ok.length !== lines.length || ok.length > KEEP * 10) fs.writeFileSync(file, ok.slice(-KEEP * 10).join('\n') + (ok.length ? '\n' : ''));
+    } catch { /* no file */ }
+  };
+  if (keep) { prune(); try { list = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter(fresh).slice(-KEEP); } catch { /* none */ } }
+  let lastPrune = now();
+  return {
+    record(name, args, outcome, extra) {
+      const e = { t: now(), tool: String(name), target: target(args), outcome, ...(extra && typeof extra === 'object' ? extra : {}) };
+      list.push(e); if (list.length > KEEP) list.shift();
+      if (keep) {
+        try { fs.appendFileSync(file, JSON.stringify(e) + '\n'); } catch { /* read-only */ }
+        if (now() - lastPrune > 86400000) { lastPrune = now(); prune(); }
+      }
+      return e;
+    },
+    list: () => [...list].reverse(),
+    clear() { list = []; try { fs.rmSync(file, { force: true }); } catch { /* none */ } },
+    setKeep(v) { keep = !!v; if (!keep) { try { fs.rmSync(file, { force: true }); } catch { /* none */ } } else for (const e of list) try { fs.appendFileSync(file, JSON.stringify(e) + '\n'); } catch { /* */ } },
+    get keep() { return keep; },
+  };
+}
+
+/** Result of a call → ok | error | refused | not confirmed | paused. */
+export const outcomeOf = (r) => (r?.paused ? 'paused' : r?.notConfirmed ? 'not confirmed' : r?.refused ? 'refused' : r?.isError ? 'error' : 'ok');

package/src/recipes.mjs

@@ -0,0 +1,108 @@
+// LOGIC: see critical-logic/bridge.md ("Automations and recipes"). Ready-made PowerShell scripts
+// (recipes/*.json in the package): the AI runs one with parameters or saves it as an automation.
+// A recipe becomes ONE plain script: a `$P = @{…}` block with the checked parameters (single-quoted
+// literals, every quote character doubled), then the recipe's own lines. Paths go through the same
+// folder rules as the file tools (tool-lib guard); the whole script then through policy.check like a
+// terminal command (bridge.mjs / automations.mjs), so an excluded folder can't hide in a parameter.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandVars, norm } from './policy.mjs';
+import { ToolError, fail, guard, excludedInside } from './tool-lib.mjs';
+
+export const RECIPE_IDS = ['backup-folder', 'clean-downloads', 'sort-folder', 'disk-report', 'update-apps'];
+const DIR = new URL('../recipes/', import.meta.url);
+let cache = null;
+export function loadRecipes() {
+  cache ||= RECIPE_IDS.map((id) => JSON.parse(fs.readFileSync(new URL(`${id}.json`, DIR), 'utf8')));
+  return cache;
+}
+const byId = (id) => loadRecipes().find((r) => r.id === id) || fail('NO_RECIPE', `There is no recipe "${id}".`, `Use one of: ${RECIPE_IDS.join(', ')} (action "recipes" lists them).`);
+
+/** What the AI gets from action "recipes" (English, parameters with types and defaults). */
+export function recipeList(lang = 'en') {
+  const l = (o) => (o && (o[lang] || o.en)) || '';
+  return loadRecipes().map((r) => ({
+    id: r.id, title: l(r.title), description: l(r.description), suggestedSchedule: r.schedule,
+    params: r.params.map((p) => ({ name: p.name, type: p.type, ...(p.required ? { required: true } : {}), ...(p.default !== undefined ? { default: p.default } : {}), ...(p.values ? { values: p.values } : {}), ...(p.min !== undefined ? { min: p.min, max: p.max } : {}), description: l(p.description) })),
+  }));
+}
+export const recipeTitle = (id) => { const r = loadRecipes().find((x) => x.id === id); return r ? r.title : null; };
+
+// PowerShell single-quoted literal. PowerShell treats ' ‘ ’ ‚ ‛ all as single quotes; doubling each
+// one keeps it literal. Control characters are refused before this (no line breaks in a value).
+export const psQuote = (s) => `'${String(s).replace(/['‘’‚‛]/g, (c) => c + c)}'`;
+const CTRL = /[\u0000-\u001f\u007f\u2028\u2029]/;
+
+// The Recycle Bin helper of the bridge itself (recycle.ps1, IFileOperation without UI; an item that
+// would be deleted for good is left alone). Copied into the script: a scheduled run needs no package.
+export function recycleLib() {
+  const t = fs.readFileSync(fileURLToPath(new URL('./recycle.ps1', import.meta.url)), 'utf8');
+  const m = /Add-CachedType @'\r?\n([\s\S]*?)\r?\n'@/.exec(t);
+  if (!m || !/class BrRecycle\b/.test(m[1])) throw new ToolError('INTERNAL', 'The Recycle Bin helper of this Bridgerator version could not be read.', 'Update Bridgerator.');
+  // Plain Add-Type (not ask-lib's Add-CachedType): its cache is in Bridgerator's own folder, which a
+  // recipe / scheduled script may never name (policy.check refuses such a script).
+  return `Add-Type -TypeDefinition @'\n${m[1]}\n'@`;
+}
+
+/** Relative folder path → "<depth>:<first 16 hex of SHA-256 of it in lower case>" (the recipe's walk computes the same). */
+export const skipId = (rel) => `${rel.split(/[\\/]/).length}:${crypto.createHash('sha256').update(rel.toLowerCase(), 'utf8').digest('hex').slice(0, 16)}`;
+
+function readParam(ctx, spec, v, all, skips = {}) {
+  const bad = (why) => fail('BAD_ARGS', `${spec.name}: ${why}.`);
+  if (spec.type === 'bool') { if (typeof v !== 'boolean') bad('must be true or false'); return v; }
+  if (spec.type === 'int') { if (!Number.isInteger(v) || v < spec.min || v > spec.max) bad(`must be a whole number from ${spec.min} to ${spec.max}`); return v; }
+  if (spec.type === 'enum') { if (!spec.values.includes(v)) bad(`must be one of ${spec.values.join(', ')}`); return v; }
+  if (spec.type === 'path') {
+    if (typeof v !== 'string' || !v.trim() || v.length > 1000 || CTRL.test(v)) bad('must be a full folder or file path on one line');
+    // A folder parameter is used as a whole tree (copied, walked, recycled below it): it must not contain an
+    // excluded / Bridgerator folder (FOLDER_HAS_EXCLUDED), except tree "skip": the script skips them itself.
+    const write = spec.access === 'write', folder = !spec.ext;
+    const abs = guard(ctx, expandVars(v.trim()), { write, tree: folder && spec.tree !== 'skip' });
+    if (folder && spec.tree === 'skip') skips[spec.name] = excludedInside(ctx, abs, { write }).map(skipId);
+    if (spec.mustExist) { let ok = false; try { ok = fs.statSync(abs).isDirectory(); } catch { /* missing */ } if (!ok) fail('NOT_FOUND', `${spec.name}: the folder "${abs}" does not exist.`, 'Check the path (list the folder first).'); }
+    if (spec.ext && path.extname(abs).toLowerCase() !== spec.ext) bad(`must end with ${spec.ext}`);
+    if (spec.notInside && all[spec.notInside]) {
+      const a = norm(abs), b = norm(all[spec.notInside]);
+      if (a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep)) bad(`must not be inside ${spec.notInside} (or contain it)`);
+    }
+    return abs;
+  }
+  bad('unknown type');
+}
+
+/**
+ * → { recipe: id, params: {checked values}, script }. ctx: { cfg, policy } (folder rules).
+ * Throws ToolError on a wrong / missing parameter or a path the folder rules refuse.
+ */
+export function buildRecipe(ctx, id, input = {}) {
+  const r = byId(id);
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) fail('BAD_ARGS', 'params must be an object.');
+  const unknown = Object.keys(input).filter((k) => !r.params.some((p) => p.name === k));
+  if (unknown.length) fail('BAD_ARGS', `Unknown parameter(s) for ${id}: ${unknown.join(', ')}.`, `Parameters: ${r.params.map((p) => p.name).join(', ')}.`);
+  const out = {}, skips = {};
+  for (const spec of r.params) {
+    let v = input[spec.name];
+    if (v === undefined || v === null || v === '') {
+      if (spec.required) fail('BAD_ARGS', `${spec.name} is required for ${id}.`);
+      if (spec.default === undefined) { out[spec.name] = null; continue; }
+      v = spec.default;
+    }
+    out[spec.name] = readParam(ctx, spec, v, out, skips);
+  }
+  const lit = (v) => (v === null ? '$null' : typeof v === 'boolean' ? (v ? '$true' : '$false') : typeof v === 'number' ? String(v) : psQuote(v));
+  const body = r.script.join('\n').replace('#RECYCLE#', () => recycleLib());
+  const script = [
+    `# Recipe "${r.id}" (${r.title.en}). Parameters:`,
+    "$ErrorActionPreference = 'Continue'",
+    '$P = @{',
+    ...r.params.map((p) => `  ${p.name} = ${lit(out[p.name])}`),
+    // Excluded folders below a tree "skip" folder as "<depth>:<hash of the relative path>" (skipId): the
+    // script never names them (it may not mention an excluded folder or Bridgerator).
+    ...Object.entries(skips).map(([k, l]) => `  ${k}Skip = @(${l.map(psQuote).join(', ')})`),
+    '}',
+    body,
+  ].join('\n');
+  return { recipe: r.id, params: out, script };
+}

package/src/recycle.mjs

@@ -0,0 +1,185 @@
+// LOGIC: see critical-logic/bridge.md ("Recycle Bin"). A delete command the AI runs in the terminal
+// goes to the Recycle Bin instead, when Bridgerator can read it for sure: ONE delete statement
+// (Remove-Item / ri / rm / del / erase / rd / rmdir, optionally inside `cmd /c`) with plain paths or a
+// wildcard in the last part. Anything else (pipes, ;, &&, variables, loops, scripts, other programs
+// that delete) runs as written — a safety net, not a guarantee (said so in the window and on the site).
+// The move itself: recycle.ps1 (IFileOperation; an item the shell would delete for good is left alone
+// and reported 'nobin' → the bridge asks on the PC before a permanent delete).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { POWERSHELL, psArgs } from './win.mjs';
+import { runFilesPs, stripOurs } from './ask.mjs';
+
+const VERBS = new Set(['remove-item', 'ri', 'rm', 'del', 'erase', 'rd', 'rmdir']);
+const MAX_TARGETS = 1000;
+const RECURSE = new Set(['-recurse', '-r', '-rf', '-fr', '--recursive', '/s']);
+const QUIET = new Set(['-force', '-f', '--force', '-v', '-verbose', '/q', '/f', '/a', '-confirm:$false']);
+
+function tokenize(s) {
+  const out = [];
+  let cur = '', q = null, quoted = false;
+  const push = () => { if (cur || quoted) out.push({ v: cur, quoted }); cur = ''; quoted = false; };
+  for (const ch of s) {
+    if (q) { if (ch === q) q = null; else cur += ch; continue; }
+    if (ch === '"' || ch === "'") { q = ch; quoted = true; continue; }
+    if (/\s/.test(ch)) { push(); continue; }
+    if (ch === ',') { push(); out.push({ v: ',', sep: true }); continue; }
+    cur += ch;
+  }
+  if (q) return null;                       // unbalanced quote
+  push();
+  return out;
+}
+
+const hasWild = (s) => /[*?]/.test(s);
+const wildRe = (seg) => new RegExp(`^${seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i');
+const kindOf = (p) => { try { const s = fs.lstatSync(p); return s.isDirectory() ? 'dir' : 'file'; } catch { return null; } };
+const isEmptyDir = (p) => { try { return fs.readdirSync(p).length === 0; } catch { return false; } };
+
+/**
+ * One delete command → { verb, targets: [absolute paths], recurse } when Bridgerator can do exactly
+ * what it asks (each target exists, folders only with a recurse flag or empty), else null (the
+ * command then runs as written).
+ */
+export function parseDelete(command, cwd = os.homedir(), home = os.homedir()) {
+  let s = String(command ?? '').trim();
+  if (!s || s.length > 4000) return null;
+  const wrapped = /^cmd(?:\.exe)?\s+\/[ck]\s+(.+)$/i.exec(s);
+  if (wrapped) { s = wrapped[1].trim(); if (/^"[^"]*"$/.test(s)) s = s.slice(1, -1); }
+  s = s.replace(/\s-Confirm:\$false\b/gi, ' -confirm:$false');
+  // Only plain text: no statements, pipes, redirects, variables, sub-expressions, escapes, line breaks.
+  if (/[;&|<>`\r\n{}()@%]/.test(s) || /\$(?!false\b)/i.test(s)) return null;
+  const tok = tokenize(s);
+  if (!tok || !tok.length) return null;
+  const verb = tok[0].v.toLowerCase().replace(/\.exe$/, '');
+  if (tok[0].quoted || !VERBS.has(verb)) return null;
+  const cmdStyle = ['del', 'erase', 'rd', 'rmdir'].includes(verb);
+  let recurse = false, literal = false, force = false, allAttrs = false;
+  const raw = [];
+  for (let i = 1; i < tok.length; i++) {
+    const t = tok[i];
+    if (t.sep) continue;
+    const low = t.v.toLowerCase();
+    if (!t.quoted && /^(-|\/[a-z]|\/[a-z]:)/i.test(t.v) && !/^\/[a-z]:?[\\/]/i.test(t.v)) {
+      if (RECURSE.has(low)) { recurse = true; continue; }
+      if (low === '-force' || low === '/f') force = true;
+      if (low === '/a') allAttrs = true;
+      if (/^\/a:[a-z-]+$/.test(low)) { allAttrs = 'filter'; continue; }
+      if (QUIET.has(low)) continue;
+      if (low === '-path') continue;
+      if (low === '-literalpath' || low === '-lp') { literal = true; continue; }
+      if (low === '-erroraction' || low === '-ea') { i++; continue; }
+      return null;                          // a flag we don't know: run as written
+    }
+    raw.push(t.v);
+  }
+  if (!raw.length || (cmdStyle && (verb === 'del' || verb === 'erase') && recurse)) return null; // del /s *.tmp: every subfolder
+  const targets = [];
+  // Wildcard matches the command itself would skip: hidden / system items (del without /a,
+  // Remove-Item without -Force) and read-only files (without /f or -Force). Checked by recycle.ps1.
+  const skip = cmdStyle ? `${allAttrs === true ? '' : 'hs'}${force ? '' : 'r'}` : force ? '' : 'hsr';
+  const wild = [];
+  for (let p of raw) {
+    if (/^[\\/]{2}/.test(p) || /^[a-z][a-z0-9+.-]*:\/\//i.test(p)) return null;
+    if (!literal && /[[\]]/.test(p)) return null;
+    if (p === '~' || /^~[\\/]/.test(p)) p = path.join(home, p.slice(1));
+    const abs = path.resolve(cwd, p);
+    if (!literal && hasWild(abs)) {
+      const dir = path.dirname(abs), seg = path.basename(abs);
+      // rd / rmdir take no wildcards; /a:<attributes> filters we don't copy: run as written.
+      if (hasWild(dir) || verb === 'rd' || verb === 'rmdir' || allAttrs === 'filter') return null;
+      let names;
+      try { names = fs.readdirSync(dir); } catch { return null; }
+      const re = wildRe(seg);
+      const hits = names.filter((n) => re.test(n)).map((n) => path.join(dir, n));
+      if (!hits.length) return null;
+      for (const h of hits) {
+        const k = kindOf(h);
+        if (k === 'dir') { if (verb === 'del' || verb === 'erase') continue; if (!recurse && !isEmptyDir(h)) return null; }
+        targets.push(h);
+        wild.push(h);
+      }
+      continue;
+    }
+    const k = kindOf(abs);
+    if (!k) return null;
+    if (k === 'dir' && (verb === 'del' || verb === 'erase')) return null; // del <folder> deletes the files inside
+    if (k === 'dir' && !recurse && !isEmptyDir(abs)) return null;
+    if (k === 'file' && (verb === 'rd' || verb === 'rmdir')) return null;
+    targets.push(abs);
+  }
+  const uniq = [...new Set(targets)];
+  if (!uniq.length || uniq.length > MAX_TARGETS) return null;
+  return { verb, targets: uniq, recurse, ...(wild.length && skip ? { skip: Object.fromEntries(wild.map((h) => [h, skip])) } : {}) };
+}
+
+const LIB = fileURLToPath(new URL('./ask-lib.ps1', import.meta.url));
+const PS = fileURLToPath(new URL('./recycle.ps1', import.meta.url));
+
+/**
+ * Moves the paths to the Recycle Bin → [{ p, r: 'recycled' | 'nobin' | 'missing' | 'skipped' | 'error:…' }].
+ * skip: { path: 'hsr' } — leave that item alone ('skipped') when it is hidden (h) / system (s) / read-only (r).
+ */
+export function recycle(paths, { timeoutMs = 120000, skip = {} } = {}) {
+  if (process.platform !== 'win32') return Promise.resolve(paths.map((p) => ({ p, r: 'nobin' })));
+  return new Promise((resolve) => {
+    const fail = (why) => resolve(paths.map((p) => ({ p, r: `error:${why}` })));
+    const chunks = [];
+    let done = false;
+    const child = spawn(POWERSHELL, psArgs(runFilesPs(LIB, PS)), { windowsHide: true, env: stripOurs(process.env), stdio: ['pipe', 'pipe', 'pipe'] });
+    const timer = setTimeout(() => { try { child.kill(); } catch { /* gone */ } if (!done) { done = true; fail('timeout'); } }, timeoutMs);
+    child.stdout.on('data', (b) => { chunks.push(b); }); // decoded once at the end: a UTF-8 character may span chunks
+    child.stderr.on('data', () => {});
+    child.on('error', (e) => { clearTimeout(timer); if (!done) { done = true; fail(e.code || 'spawn'); } });
+    child.on('close', () => {
+      clearTimeout(timer);
+      if (done) return;
+      done = true;
+      try {
+        const r = JSON.parse(Buffer.concat(chunks).toString('utf8').trim().split(/\r?\n/).pop());
+        const list = Array.isArray(r) ? r : [r];
+        resolve(paths.map((p) => list.find((x) => x && x.p === p) || { p, r: 'error:no-answer' }));
+      } catch { fail('bad-answer'); }
+    });
+    // PowerShell gone early (EPIPE): the error is reported through 'close' / the timeout, never thrown.
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(paths.map((p) => ({ p, skip: typeof skip[p] === 'string' ? skip[p] : '' }))));
+  });
+}
+
+// --- Undo of a delete: the restored item's copy leaves the Recycle Bin too ----------------------
+// Each recycled item is a pair in <drive>\$Recycle.Bin\<SID>\: $I<id> (original path + deletion time)
+// and $R<id> (the item itself). Only this user's folder is readable, so only their items match.
+const FILETIME_EPOCH_MS = 11644473600000;
+/** $I file → { path, t } (format 1: Vista–8, 2: Windows 10+), or null. */
+export function readBinInfo(buf) {
+  try {
+    const v = Number(buf.readBigInt64LE(0));
+    const t = Number(buf.readBigInt64LE(16) / 10000n) - FILETIME_EPOCH_MS;
+    const p = v === 2 ? buf.toString('utf16le', 28, 28 + (buf.readUInt32LE(24) - 1) * 2) : v === 1 ? buf.toString('utf16le', 24, 24 + 520) : null;
+    return p ? { path: p.replace(/\0.*$/s, ''), t } : null;
+  } catch { return null; }
+}
+/**
+ * Removes from the Recycle Bin exactly the copies this bridge made: items = [{ path, bin }], bin = the
+ * $R path recycle.ps1 reported when it recycled `path`. Removed only when that pair is still there and
+ * its $I names that same original path; an item without a recorded copy is left alone (never another
+ * bin entry — it may be the person's own later deletion). → the paths whose bin copy was removed. Never throws.
+ */
+export function purgeFromBin(items) {
+  const gone = [];
+  for (const it of Array.isArray(items) ? items : []) {
+    try {
+      const r = typeof it?.bin === 'string' ? path.resolve(it.bin) : '', n = path.basename(r);
+      if (!/^\$R/i.test(n) || path.basename(path.dirname(path.dirname(r))).toLowerCase() !== '$recycle.bin') continue;
+      const i = path.join(path.dirname(r), `$I${n.slice(2)}`);
+      const info = readBinInfo(fs.readFileSync(i));
+      if (!info || path.resolve(info.path).toLowerCase() !== path.resolve(String(it.path)).toLowerCase()) continue;
+      fs.rmSync(r, { recursive: true, force: true }); fs.rmSync(i, { force: true }); gone.push(it.path);
+    } catch { /* gone already / in use: stays in the bin */ }
+  }
+  return gone;
+}