@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/wiki/notes.js

@@ -0,0 +1,297 @@
+// The Wiki: plain Markdown notes about projects, linked to each other. It is reference material
+// a person and agents read and write; it is not what shapes an agent (that is the variant).
+//
+//   <data>/wiki/home.md
+//   <data>/wiki/library/**.md          notes that belong to no project
+//   <data>/wiki/projects/<slug>/**.md  a project's notes
+//   <data>/wiki-history/<path>/<time>.md  earlier versions, one file per save
+//
+// A note's path is its file path without `.md`. Links are `[[path]]`, `[[path|label]]`, or a
+// Markdown link to a relative `.md` file.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { noteChange } from "../core/changes.js";
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { atomicWrite, now } from "../core/fs.js";
+import { projectsOrNone } from "../core/projects.js";
+import { looksSecret } from "../core/secrets.js";
+/** Folders an earlier Wiki kept beside its pages. They are moved aside, never read as notes. */
+export const LEGACY_FOLDERS = ['blocks', 'facts', 'raw', 'revisions', 'inbox', 'operations', 'trash'];
+const MAX_NOTE = 400_000;
+export function wikiDir(root) {
+    return join(root, 'wiki');
+}
+function historyDir(root) {
+    return join(root, 'wiki-history');
+}
+/** Accepts a note path such as `projects/app/decisions` or `library/glossary`. */
+export function cleanPath(path) {
+    const clean = String(path ?? '').trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '').replace(/\.md$/i, '');
+    const parts = clean.split('/');
+    if (!clean || parts.some((part) => !part || part === '.' || part === '..' || part.startsWith('.')))
+        throw invalid('A note path is a relative path such as projects/<slug>/<name>.');
+    if (parts.length === 1 && clean !== 'home')
+        throw invalid('A note lives under library/ or projects/<slug>/.');
+    if (parts.length > 1 && parts[0] !== 'library' && parts[0] !== 'projects')
+        throw invalid('A note lives under library/ or projects/<slug>/.');
+    if (parts[0] === 'projects' && parts.length < 3)
+        throw invalid('A project note is projects/<slug>/<name>.');
+    if (LEGACY_FOLDERS.includes(parts[0]))
+        throw invalid('That folder is not part of the Wiki.');
+    return clean;
+}
+function fileOf(root, path) {
+    return join(wikiDir(root), `${cleanPath(path)}.md`);
+}
+function projectOfPath(path) {
+    const parts = path.split('/');
+    return parts[0] === 'projects' ? parts[1] ?? null : null;
+}
+function titleOf(path, text) {
+    const parsed = safeParse(text);
+    const declared = parsed.front?.title;
+    if (typeof declared === 'string' && declared.trim())
+        return declared.trim();
+    const heading = /^#\s+(.+)$/m.exec(parsed.body)?.[1]?.trim();
+    return heading || path.split('/').pop().replace(/[-_]/g, ' ');
+}
+function safeParse(text) {
+    try {
+        const parsed = frontmatter.parse(text);
+        return parsed ? { front: parsed.front, body: parsed.body } : { front: null, body: text };
+    }
+    catch {
+        return { front: null, body: text };
+    }
+}
+function walk(dir, into) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names.sort()) {
+        if (name.startsWith('.'))
+            continue;
+        const path = join(dir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(path).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            walk(path, into);
+        else if (name.endsWith('.md'))
+            into.push(path);
+    }
+}
+/** Every note path, Home first, then the Library, then projects. */
+export function paths(root) {
+    const wiki = wikiDir(root);
+    const files = [];
+    if (existsSync(join(wiki, 'home.md')))
+        files.push(join(wiki, 'home.md'));
+    walk(join(wiki, 'library'), files);
+    walk(join(wiki, 'projects'), files);
+    return files.map((file) => relative(wiki, file).split(sep).join('/').replace(/\.md$/, ''));
+}
+function summary(root, path) {
+    const file = fileOf(root, path);
+    const text = readFileSync(file, 'utf8');
+    return { path, title: titleOf(path, text), project: projectOfPath(path), updatedAt: statSync(file).mtime.toISOString(), size: text.length };
+}
+export function list(root, options = {}) {
+    return paths(root)
+        .filter((path) => options.project === undefined || projectOfPath(path) === options.project)
+        .map((path) => summary(root, path));
+}
+const WIKI_LINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+const MD_LINK = /\[[^\]]*\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
+/** Resolves a link written in `from` to a note path, or null when it points nowhere known. */
+export function resolveLink(target, from, known, titles) {
+    const raw = target.trim().replace(/\.md$/i, '');
+    if (!raw || /^[a-z]+:/i.test(raw))
+        return null;
+    const candidates = [raw.replace(/^\/+/, '')];
+    if (!raw.startsWith('/')) {
+        const base = from.split('/').slice(0, -1);
+        const parts = [...base];
+        for (const part of raw.split('/')) {
+            if (part === '..')
+                parts.pop();
+            else if (part && part !== '.')
+                parts.push(part);
+        }
+        candidates.unshift(parts.join('/'));
+        const project = projectOfPath(from);
+        if (project)
+            candidates.push(`projects/${project}/${raw}`);
+        candidates.push(`library/${raw}`);
+    }
+    for (const candidate of candidates)
+        if (known.has(candidate))
+            return candidate;
+    return titles.get(raw.toLowerCase()) ?? null;
+}
+function linksIn(body, from, known, titles) {
+    const out = new Set();
+    for (const match of body.matchAll(WIKI_LINK)) {
+        const found = resolveLink(match[1], from, known, titles);
+        if (found && found !== from)
+            out.add(found);
+    }
+    for (const match of body.matchAll(MD_LINK)) {
+        const found = resolveLink(match[1], from, known, titles);
+        if (found && found !== from)
+            out.add(found);
+    }
+    return [...out].sort();
+}
+/** Every note and every resolved link between notes. */
+export function graph(root) {
+    const nodes = list(root);
+    const known = new Set(nodes.map((node) => node.path));
+    const titles = new Map(nodes.map((node) => [node.title.toLowerCase(), node.path]));
+    const edges = [];
+    for (const node of nodes) {
+        const body = readFileSync(fileOf(root, node.path), 'utf8');
+        for (const to of linksIn(body, node.path, known, titles))
+            edges.push({ from: node.path, to });
+    }
+    return { nodes, edges };
+}
+export function read(root, path) {
+    const clean = cleanPath(path);
+    const file = fileOf(root, clean);
+    if (!existsSync(file))
+        throw notFound(`The note ${clean}`);
+    const text = readFileSync(file, 'utf8');
+    const { nodes, edges } = graph(root);
+    const known = new Set(nodes.map((node) => node.path));
+    const titles = new Map(nodes.map((node) => [node.title.toLowerCase(), node.path]));
+    return {
+        ...summary(root, clean),
+        body: text,
+        links: linksIn(text, clean, known, titles),
+        backlinks: edges.filter((edge) => edge.to === clean).map((edge) => edge.from).sort()
+    };
+}
+/** Writes a note, keeping the earlier text as a version. Returns the note as saved. */
+export function write(root, path, body, options = {}) {
+    const clean = cleanPath(path);
+    if (typeof body !== 'string')
+        throw invalid('A note needs text.');
+    if (body.length > MAX_NOTE)
+        throw invalid(`A note may hold at most ${MAX_NOTE.toLocaleString('en-US')} characters.`);
+    if (looksSecret(body))
+        throw new HarnessError('secret_refused', 'That text looks like it contains a credential, so it was not saved.');
+    const project = projectOfPath(clean);
+    if (project && !projectsOrNone(root).some((known) => known.slug === project))
+        throw invalid(`There is no project with the slug ${project}.`);
+    const file = fileOf(root, clean);
+    if (existsSync(file)) {
+        const current = statSync(file).mtime.toISOString();
+        if (options.expectedUpdatedAt && options.expectedUpdatedAt !== current)
+            throw new HarnessError('conflict', 'The note changed since it was opened. Reload it and try again.');
+        const previous = readFileSync(file, 'utf8');
+        if (previous === body)
+            return read(root, clean);
+        atomicWrite(join(historyDir(root), clean, `${now().replace(/[:.]/g, '-')}.md`), previous);
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    atomicWrite(file, body);
+    noteChange({ wiki: wikiDir(root), id: clean, path: file, text: body, actor: options.actor ?? 'user', reason: options.reason ?? 'Saved' });
+    return read(root, clean);
+}
+/** Removes a note; its last text is kept as a version. */
+export function remove(root, path) {
+    const clean = cleanPath(path);
+    const file = fileOf(root, clean);
+    if (!existsSync(file))
+        throw notFound(`The note ${clean}`);
+    atomicWrite(join(historyDir(root), clean, `${now().replace(/[:.]/g, '-')}.md`), readFileSync(file, 'utf8'));
+    rmSync(file);
+}
+export function versions(root, path) {
+    const dir = join(historyDir(root), cleanPath(path));
+    try {
+        return readdirSync(dir).filter((name) => name.endsWith('.md')).sort().reverse().map((name) => ({ id: name.replace(/\.md$/, ''), savedAt: statSync(join(dir, name)).mtime.toISOString() }));
+    }
+    catch {
+        return [];
+    }
+}
+export function version(root, path, id) {
+    if (!/^[0-9A-Za-z-]+$/.test(id))
+        throw invalid('Invalid version.');
+    const file = join(historyDir(root), cleanPath(path), `${id}.md`);
+    if (!existsSync(file))
+        throw notFound('That version');
+    return readFileSync(file, 'utf8');
+}
+/** Notes that contain the query's words, best first. The current project's notes rank higher. */
+export function search(root, query, options = {}) {
+    const words = [...new Set(String(query ?? '').toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word.length > 1))].slice(0, 16);
+    if (!words.length)
+        return [];
+    const hits = [];
+    for (const path of paths(root)) {
+        const text = readFileSync(fileOf(root, path), 'utf8');
+        const lower = text.toLowerCase();
+        const title = titleOf(path, text);
+        let score = 0;
+        for (const word of words) {
+            if (title.toLowerCase().includes(word))
+                score += 5;
+            if (path.toLowerCase().includes(word))
+                score += 2;
+            let at = lower.indexOf(word);
+            let count = 0;
+            while (at >= 0 && count < 20) {
+                count++;
+                at = lower.indexOf(word, at + word.length);
+            }
+            score += count;
+        }
+        if (!score)
+            continue;
+        const project = projectOfPath(path);
+        if (options.project && project === options.project)
+            score *= 1.5;
+        const first = Math.max(0, Math.min(...words.map((word) => lower.indexOf(word)).filter((at) => at >= 0)));
+        const excerpt = text.slice(Math.max(0, first - 80), first + 160).replace(/\s+/g, ' ').trim();
+        hits.push({ path, title, project, excerpt, score });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, Math.min(Math.max(options.limit ?? 10, 1), 50));
+}
+/** Creates the Wiki's folders and Home note. Existing files are never replaced. */
+export function ensureLayout(root, productName) {
+    const wiki = wikiDir(root);
+    mkdirSync(join(wiki, 'library'), { recursive: true });
+    mkdirSync(join(wiki, 'projects'), { recursive: true });
+    if (!existsSync(join(wiki, 'home.md')))
+        atomicWrite(join(wiki, 'home.md'), `# Home\n\nNotes about your projects for ${productName}. Link notes with [[library/name]] or [[projects/<slug>/name]].\n`);
+    for (const project of projectsOrNone(root))
+        mkdirSync(join(wiki, 'projects', project.slug), { recursive: true });
+}
+/**
+ * Moves what an earlier Wiki kept beside its notes (memory blocks, facts, sources, revisions,
+ * the Inbox) to `<data>/legacy/wiki-<time>/`, once. Nothing is deleted. Returns where it went.
+ */
+export function moveLegacy(root) {
+    const wiki = wikiDir(root);
+    const found = LEGACY_FOLDERS.filter((name) => existsSync(join(wiki, name)));
+    const loose = ['index.md', 'log.md', 'schema.md'].filter((name) => existsSync(join(wiki, name)));
+    if (!found.length && !loose.length)
+        return null;
+    const dest = join(root, 'legacy', `wiki-${now().replace(/[:.]/g, '-')}`);
+    mkdirSync(dest, { recursive: true });
+    for (const name of [...found, ...loose])
+        renameSync(join(wiki, name), join(dest, name));
+    return dest;
+}

package/dist/sdk/wiki/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function wikiServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/wiki/serverMethods.js

@@ -0,0 +1,26 @@
+import { optional, text } from "../server/params.js";
+import * as notes from "./notes.js";
+export function wikiServerMethods(harness) {
+    const root = () => harness.env.root;
+    return {
+        'wiki.list': (params) => notes.list(root(), params.project === undefined ? {} : { project: optional(params, 'project') }),
+        'wiki.read': (params) => notes.read(root(), text(params, 'path')),
+        'wiki.write': (params) => {
+            const note = notes.write(root(), text(params, 'path'), typeof params.text === 'string' ? params.text : '', { expectedUpdatedAt: optional(params, 'expectedUpdatedAt') });
+            harness.bus.emit({ type: 'wiki.changed' });
+            return note;
+        },
+        'wiki.remove': (params) => {
+            notes.remove(root(), text(params, 'path'));
+            harness.bus.emit({ type: 'wiki.changed' });
+        },
+        'wiki.search': (params) => notes.search(root(), typeof params.query === 'string' ? params.query : '', { project: optional(params, 'project'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
+        'wiki.graph': () => notes.graph(root()),
+        'wiki.versions': (params) => notes.versions(root(), text(params, 'path')),
+        'wiki.version': (params) => notes.version(root(), text(params, 'path'), text(params, 'id')),
+        'wiki.ensureProject': () => {
+            notes.ensureLayout(root(), harness.env.productName);
+            harness.bus.emit({ type: 'wiki.changed' });
+        }
+    };
+}

package/dist/sdk/worktrees/cli.d.ts

@@ -0,0 +1,11 @@
+import { Worktrees } from "./service.js";
+import type { WorktreeRecord } from "./types.js";
+export declare const WORKTREE_USAGE = "Usage: xagent worktree <command> [--state <dir>]\n\n  list                       Worktrees of the repository you are in\n  new [name] [--branch <b>] [--permanent] [--from <ref>] [--no-carry]\n                             Make a worktree (default: managed, detached, with your\n                             uncommitted changes carried over)\n  status <name|id>           Changes and commits since it started\n  branch <name|id> <branch>  Give a detached worktree a branch\n  handoff <name|id> to-main|to-worktree [--copy]\n                             Move changes between it and your main checkout\n                             (--copy leaves the origin as it was)\n  rm <name|id> [--force]     Remove it; with --force, keep a snapshot of unsaved work\n  restore <name|id>          Bring back a removed worktree, with its snapshot\n  prune [--keep <n>]         Keep the most recent managed worktrees (default 15)\n  adopt <path>               Manage an existing linked worktree\n  trust-setup                Trust this repository's .xharness/worktree-setup as it is now\n  path <name|id>             Print its folder (cd \"$(xagent worktree path name)\")\n\nStart the terminal in a new managed worktree with: xagent --worktree [name]\n";
+interface Dependencies {
+    home?: string;
+    cwd?: string;
+    write?: (text: string) => void;
+}
+export declare function findWorktree(worktrees: Worktrees, cwd: string, key: string, removed?: boolean): Promise<WorktreeRecord>;
+export declare function runWorktreeCli(argv: string[], dependencies?: Dependencies): Promise<number>;
+export {};

package/dist/sdk/worktrees/cli.js

@@ -0,0 +1,146 @@
+// `xagent worktree`: managed worktrees of the repository you are in, from a shell.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Worktrees } from "./service.js";
+export const WORKTREE_USAGE = `Usage: xagent worktree <command> [--state <dir>]
+
+  list                       Worktrees of the repository you are in
+  new [name] [--branch <b>] [--permanent] [--from <ref>] [--no-carry]
+                             Make a worktree (default: managed, detached, with your
+                             uncommitted changes carried over)
+  status <name|id>           Changes and commits since it started
+  branch <name|id> <branch>  Give a detached worktree a branch
+  handoff <name|id> to-main|to-worktree [--copy]
+                             Move changes between it and your main checkout
+                             (--copy leaves the origin as it was)
+  rm <name|id> [--force]     Remove it; with --force, keep a snapshot of unsaved work
+  restore <name|id>          Bring back a removed worktree, with its snapshot
+  prune [--keep <n>]         Keep the most recent managed worktrees (default 15)
+  adopt <path>               Manage an existing linked worktree
+  trust-setup                Trust this repository's .xharness/worktree-setup as it is now
+  path <name|id>             Print its folder (cd "$(xagent worktree path name)")
+
+Start the terminal in a new managed worktree with: xagent --worktree [name]
+`;
+function describe(record) {
+    const state = record.branch ?? 'detached';
+    const lease = record.lease ? ' · in use' : '';
+    return `${record.name.padEnd(20)} ${record.kind.padEnd(9)} ${state.padEnd(24)} ${record.path}${lease}`;
+}
+export async function findWorktree(worktrees, cwd, key, removed = false) {
+    const repo = await worktrees.repositoryOf(cwd);
+    const pool = removed ? worktrees.removed(repo) : await worktrees.list(repo);
+    const match = pool.find((record) => record.id === key || record.name === key);
+    if (!match)
+        throw new Error(`No ${removed ? 'removed ' : ''}worktree named ${key} in this repository.`);
+    return match;
+}
+export async function runWorktreeCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    const cwd = resolve(dependencies.cwd ?? process.cwd());
+    const args = [];
+    let stateDir = join(dependencies.home ?? homedir(), '.xingular-harness', 'state');
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === '--state')
+            stateDir = resolve(argv[++index] ?? stateDir);
+        else
+            args.push(argv[index]);
+    }
+    const [command, ...rest] = args;
+    const flag = (name) => rest.includes(name);
+    const value = (name) => {
+        const index = rest.indexOf(name);
+        return index >= 0 ? rest[index + 1] : undefined;
+    };
+    const positional = rest.filter((item, index) => !item.startsWith('--') && !(index > 0 && ['--branch', '--from', '--keep'].includes(rest[index - 1])));
+    const worktrees = new Worktrees(stateDir);
+    switch (command) {
+        case 'list': {
+            const records = await worktrees.list(cwd);
+            write(records.length ? `${records.map(describe).join('\n')}\n` : 'No worktrees for this repository.\n');
+            return 0;
+        }
+        case 'new': {
+            const result = await worktrees.create({
+                repo: cwd,
+                ...(positional[0] ? { name: positional[0] } : {}),
+                ...(value('--branch') ? { branch: value('--branch') } : {}),
+                ...(value('--from') ? { baseRef: value('--from') } : {}),
+                kind: flag('--permanent') ? 'permanent' : 'managed',
+                ...(flag('--no-carry') ? { carryChanges: false } : {})
+            });
+            write(`${describe(result.worktree)}\n`);
+            if (result.carried.copied.length || result.carried.patched)
+                write(`Carried your uncommitted changes${result.carried.copied.length ? ` and ${result.carried.copied.length} untracked file(s)` : ''}.\n`);
+            if (result.included.copied.length)
+                write(`Copied ${result.included.copied.length} file(s) named in .worktreeinclude.\n`);
+            if (result.setup.state === 'untrusted')
+                write('The repository has a setup script you have not trusted. Read .xharness/worktree-setup, then run: xagent worktree trust-setup\n');
+            if (result.setup.state === 'failed')
+                write(`The setup script failed; see ${result.setup.log}.\n`);
+            return 0;
+        }
+        case 'status': {
+            const status = await worktrees.status((await findWorktree(worktrees, cwd, positional[0] ?? '')).id);
+            write(`${describe(status.record)}\n${status.changes} changed path(s), ${status.ahead} commit(s) since it started.\n`);
+            return 0;
+        }
+        case 'branch': {
+            const record = await worktrees.branch((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, positional[1] ?? '');
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'handoff': {
+            const direction = positional[1] === 'to-main' ? 'toSource' : positional[1] === 'to-worktree' ? 'toWorktree' : null;
+            if (!direction) {
+                write(WORKTREE_USAGE);
+                return 2;
+            }
+            const result = await worktrees.handoff((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, direction, { move: !flag('--copy') });
+            write(result.patched || result.copied.length ? `Handed off${result.copied.length ? ` (and ${result.copied.length} untracked file(s))` : ''}.${result.stash ? ` The origin's copy is kept in git stash ${result.stash.slice(0, 12)}.` : ''}\n` : 'Nothing to hand off.\n');
+            return 0;
+        }
+        case 'rm': {
+            const { worktree, snapshot } = await worktrees.remove((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, { force: flag('--force') });
+            write(`Removed ${worktree.name}.${snapshot ? ` Its unsaved work is kept; xagent worktree restore ${worktree.name} brings it back.` : ''}\n`);
+            return 0;
+        }
+        case 'restore': {
+            const record = await worktrees.restore((await findWorktree(worktrees, cwd, positional[0] ?? '', true)).id);
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'prune': {
+            const keep = value('--keep') ? Number(value('--keep')) : undefined;
+            const result = await worktrees.prune({ repo: cwd, ...(keep !== undefined && Number.isFinite(keep) ? { keep } : {}) });
+            write(`Removed ${result.removed.length} worktree(s)${result.removed.some((entry) => entry.snapshot) ? ', keeping snapshots of unsaved work' : ''}.\n`);
+            for (const failure of result.failed)
+                write(`Could not remove ${failure.id}: ${failure.error}\n`);
+            return result.failed.length ? 1 : 0;
+        }
+        case 'adopt': {
+            const record = await worktrees.adopt(resolve(cwd, positional[0] ?? ''));
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'trust-setup': {
+            const { setupScript } = await import("./setup.js");
+            const repo = await worktrees.repositoryOf(cwd);
+            const script = setupScript(repo);
+            if (!script) {
+                write('This repository has no .xharness/worktree-setup.\n');
+                return 1;
+            }
+            await worktrees.trustSetup(repo, script.hash);
+            write(`Trusted the setup script (sha256 ${script.hash.slice(0, 12)}…). A changed script asks again.\n`);
+            return 0;
+        }
+        case 'path': {
+            write(`${(await findWorktree(worktrees, cwd, positional[0] ?? '')).path}\n`);
+            return 0;
+        }
+        default:
+            write(WORKTREE_USAGE);
+            return command && command !== 'help' ? 2 : 0;
+    }
+}

package/dist/sdk/worktrees/copy.d.ts

@@ -0,0 +1,9 @@
+import type { CopyReport } from "./types.js";
+export declare const INCLUDE_FILE = ".worktreeinclude";
+export declare function copyFiles(from: string, to: string, paths: readonly string[]): CopyReport;
+/** Untracked files that are not ignored: new work a person has not added yet. */
+export declare function untrackedFiles(checkout: string): Promise<string[]>;
+/** All ignored user files that must be bounded and captured before a worktree is removed. */
+export declare function ignoredFiles(checkout: string): Promise<string[]>;
+/** Ignored files that match `.worktreeinclude`, matched by git itself. */
+export declare function includedFiles(checkout: string): Promise<string[]>;

package/dist/sdk/worktrees/copy.js

@@ -0,0 +1,111 @@
+// Copies files git does not track into a worktree: untracked work carried from the source, and the
+// ignored files `.worktreeinclude` names (local settings, `.env`). A file is never overwritten, a
+// symlink is never followed, and sizes are capped.
+import { copyFileSync, existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { HarnessError } from "../core/errors.js";
+import { safeRelative } from "../core/fs.js";
+import { git, nulList } from "./git.js";
+export const INCLUDE_FILE = '.worktreeinclude';
+const FILE_CAP = 5 * 1024 * 1024;
+const TOTAL_CAP = 100 * 1024 * 1024;
+const IGNORED_FILE_COUNT_CAP = 10_000;
+const IGNORED_PATH_BYTES_CAP = 1024 * 1024;
+export function copyFiles(from, to, paths) {
+    const report = { copied: [], skipped: [] };
+    let total = 0;
+    for (const path of paths) {
+        let relative;
+        try {
+            relative = safeRelative(path);
+        }
+        catch {
+            continue;
+        }
+        const source = join(from, relative);
+        const target = join(to, relative);
+        if (existsSync(target)) {
+            report.skipped.push({ path: relative, reason: 'exists' });
+            continue;
+        }
+        let stat;
+        try {
+            stat = lstatSync(source);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink()) {
+            report.skipped.push({ path: relative, reason: 'symlink' });
+            continue;
+        }
+        if (!stat.isFile()) {
+            report.skipped.push({ path: relative, reason: 'not_file' });
+            continue;
+        }
+        if (stat.size > FILE_CAP) {
+            report.skipped.push({ path: relative, reason: 'too_large' });
+            continue;
+        }
+        if (total + stat.size > TOTAL_CAP) {
+            report.skipped.push({ path: relative, reason: 'over_total' });
+            continue;
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(source, target);
+        total += stat.size;
+        report.copied.push(relative);
+    }
+    return report;
+}
+/** Untracked files that are not ignored: new work a person has not added yet. */
+export async function untrackedFiles(checkout) {
+    return nulList((await git(checkout, ['ls-files', '--others', '--exclude-standard', '-z'])).stdout);
+}
+/** All ignored user files that must be bounded and captured before a worktree is removed. */
+export async function ignoredFiles(checkout) {
+    const paths = nulList((await git(checkout, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'])).stdout);
+    if (paths.length > IGNORED_FILE_COUNT_CAP)
+        throw ignoredFilesError(`there are more than ${IGNORED_FILE_COUNT_CAP} ignored files`);
+    let total = 0;
+    let pathBytes = 0;
+    return paths.map((path) => {
+        let relative;
+        try {
+            relative = safeRelative(path);
+        }
+        catch {
+            throw ignoredFilesError('an ignored path is unsafe');
+        }
+        pathBytes += Buffer.byteLength(relative) + 10;
+        if (pathBytes > IGNORED_PATH_BYTES_CAP)
+            throw ignoredFilesError('the ignored paths exceed the snapshot limit');
+        let stat;
+        try {
+            stat = lstatSync(join(checkout, relative));
+        }
+        catch {
+            throw ignoredFilesError(`could not inspect ${relative}`);
+        }
+        if (!stat.isFile() && !stat.isSymbolicLink())
+            throw ignoredFilesError(`${relative} is not a regular file or symlink`);
+        if (stat.size > FILE_CAP)
+            throw ignoredFilesError(`${relative} exceeds the ${FILE_CAP}-byte per-file limit`);
+        total += stat.size;
+        if (total > TOTAL_CAP)
+            throw ignoredFilesError(`ignored files exceed the ${TOTAL_CAP}-byte total limit`);
+        return relative;
+    });
+}
+function ignoredFilesError(reason) {
+    return new HarnessError('worktree_has_work', `Ignored files cannot be safely preserved: ${reason}.`, 'Move or remove those files, then try again.');
+}
+/** Ignored files that match `.worktreeinclude`, matched by git itself. */
+export async function includedFiles(checkout) {
+    const patterns = join(checkout, INCLUDE_FILE);
+    if (!existsSync(patterns))
+        return [];
+    const ignored = new Set(nulList((await git(checkout, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'])).stdout));
+    const matching = nulList((await git(checkout, ['ls-files', '--others', '--ignored', `--exclude-from=${patterns}`, '-z'])).stdout);
+    return matching.filter((path) => ignored.has(path));
+}

package/dist/sdk/worktrees/git.d.ts

@@ -0,0 +1,16 @@
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface GitOptions {
+    input?: string | Buffer;
+    env?: Record<string, string>;
+    /** Return a failed result instead of throwing. */
+    allowFail?: boolean;
+}
+export declare function git(cwd: string, args: readonly string[], options?: GitOptions): Promise<GitResult>;
+/** The trimmed standard output of a git command that must succeed. */
+export declare function gitText(cwd: string, args: readonly string[], options?: GitOptions): Promise<string>;
+/** NUL-separated output as a list, without the empty last entry. */
+export declare function nulList(text: string): string[];