@qvac/harness 0.8.8 → 0.8.10

package/dist-lib/lib/tools/files/read-file.js

@@ -0,0 +1,103 @@
+import b4a from 'b4a';
+import { errorMessage } from '../../guards.js';
+import { documentText, isDocument } from '../fs/document-text.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { anchorOf, positiveInt, resolveRooted, rootedPath, stringArg } from '../fs/tool-path.js';
+const READ_LINES = 400;
+const READ_CHARS = 20_000;
+const BINARY_PROBE = 1024;
+export function createReadFileTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'read_file',
+        toolset: 'files',
+        description: 'Read one file from the shared folder. Lines come back numbered ("12| text"). For a long file, ' +
+            'read a range with startLine/endLine. PDF, Word and PowerPoint files come back as their text. ' +
+            'Use this, not exec, for files in the shared folder.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path, relative to the shared folder' },
+                startLine: { type: 'integer', description: 'First line to read (1-based, optional)' },
+                endLine: { type: 'integer', description: 'Last line to read (optional)' }
+            },
+            required: ['path']
+        },
+        effect: () => 'read',
+        stableRead: true,
+        autoApprove: true,
+        rootsRequired: true,
+        validate: (args) => (stringArg(args, 'path') ? null : 'path is required'),
+        resource(args, ctx) {
+            const requested = stringArg(args, 'path');
+            return requested ? { kind: 'file', label: rootedPath(requested, anchorOf(ctx)) } : null;
+        },
+        async execute(args, ctx) {
+            const requested = String(args.path);
+            const resolved = await resolveRooted(requested, {
+                grants: ctx,
+                write: false,
+                realpath,
+                deniedRoots
+            });
+            if ('error' in resolved) {
+                return resolved;
+            }
+            try {
+                const text = await textOf(resolved, requested);
+                if (typeof text !== 'string') {
+                    return text;
+                }
+                return numbered(text, {
+                    start: positiveInt(args.startLine),
+                    end: positiveInt(args.endLine)
+                });
+            }
+            catch (err) {
+                return { error: errorMessage(err) };
+            }
+        }
+    };
+}
+async function textOf(resolved, requested) {
+    const { drive } = resolved.root;
+    const bytes = (await drive.entry(resolved.key)) ? await drive.get(resolved.key) : null;
+    if (bytes === null) {
+        return { error: `no such file: ${requested}. Use list_dir or glob to find the right path.` };
+    }
+    if (isDocument(resolved.key)) {
+        return documentText(resolved.key, bytes);
+    }
+    if (bytes.subarray(0, BINARY_PROBE).includes(0)) {
+        return { error: `${requested} is a binary file (not text, PDF, Word or PowerPoint)` };
+    }
+    return b4a.toString(bytes, 'utf8');
+}
+function numbered(text, { start, end }) {
+    const lines = text.split('\n');
+    if (lines.length > 1 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    const total = lines.length;
+    const first = Math.min(start ?? 1, Math.max(total, 1));
+    const out = [];
+    let chars = 0;
+    let cut = false;
+    for (let n = first; n <= Math.min(total, end ?? first + READ_LINES - 1); n++) {
+        const row = `${n}| ${lines[n - 1]}`;
+        if (chars + row.length > READ_CHARS) {
+            cut = out.length === 0;
+            if (cut) {
+                out.push(row.slice(0, READ_CHARS));
+            }
+            break;
+        }
+        out.push(row);
+        chars += row.length + 1;
+    }
+    const last = first + out.length - 1;
+    const shown = cut
+        ? `line ${first} of ${total}, cut at ${READ_CHARS} characters`
+        : `lines ${first}-${last} of ${total}`;
+    const header = last < total ? `${shown}; continue with startLine ${last + 1}` : shown;
+    return { content: `${header}\n${out.join('\n')}` };
+}

package/dist-lib/lib/tools/files/transfer.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createMoveFileTool(options?: FsToolOptions): ToolDefinition;
+export declare function createCopyFileTool(options?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/transfer.js

@@ -0,0 +1,82 @@
+import fs from 'fs';
+import path from 'path';
+import { errorMessage } from '../../guards.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { localPathOf, resolveRooted, rootedLabel, stringArg } from '../fs/tool-path.js';
+function fromTo(from) {
+    return {
+        type: 'object',
+        properties: {
+            from: { type: 'string', description: from },
+            to: { type: 'string', description: 'New path, relative to the shared folder' }
+        },
+        required: ['from', 'to']
+    };
+}
+export function createMoveFileTool(options = {}) {
+    return {
+        ...transferTool({ ...options, copy: false }),
+        name: 'move_file',
+        parameters: fromTo('Current path, relative to the shared folder'),
+        description: 'Move or rename a file or folder inside the shared folder. Fails if the destination exists. ' +
+            'Asks the user first.',
+        effect: () => 'write',
+        autoApprove: false
+    };
+}
+export function createCopyFileTool(options = {}) {
+    return {
+        ...transferTool({ ...options, copy: true }),
+        name: 'copy_file',
+        parameters: fromTo('File to copy, relative to the shared folder'),
+        description: 'Copy a file inside the shared folder to a new path. Fails if the destination exists.',
+        effect: () => 'read'
+    };
+}
+function transferTool({ realpath = defaultRealpath, deniedRoots, copy }) {
+    return {
+        toolset: 'files',
+        writeRootsRequired: true,
+        validate: (args) => stringArg(args, 'from') && stringArg(args, 'to') ? null : 'from and to are required',
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: rootedLabel(copy ? 'copy' : 'move', {
+                grants: ctx,
+                paths: [String(args.from), String(args.to)]
+            })
+        }),
+        execute: (args, ctx) => transfer(args, ctx, { realpath, deniedRoots, copy })
+    };
+}
+async function transfer(args, ctx, { realpath = defaultRealpath, deniedRoots, copy }) {
+    const scope = { grants: ctx, write: true, realpath, deniedRoots };
+    const from = await resolveRooted(String(args.from), scope);
+    if ('error' in from) {
+        return from;
+    }
+    const to = await resolveRooted(String(args.to), scope);
+    if ('error' in to) {
+        return to;
+    }
+    const source = localPathOf(from);
+    const target = localPathOf(to);
+    if (!source || !target) {
+        return { error: 'moving and copying work only in a folder on this device' };
+    }
+    try {
+        if (!fs.existsSync(source)) {
+            return { error: `no such file: ${String(args.from)}` };
+        }
+        if (fs.existsSync(target)) {
+            return { error: `${String(args.to)} already exists` };
+        }
+        await fs.promises.mkdir(path.dirname(target), { recursive: true });
+        await (copy ? fs.promises.copyFile(source, target) : fs.promises.rename(source, target));
+        return copy
+            ? { copied: String(args.from), to: String(args.to) }
+            : { moved: String(args.from), to: String(args.to) };
+    }
+    catch (err) {
+        return { error: errorMessage(err) };
+    }
+}

package/dist-lib/lib/tools/files/trash-file.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare const TRASH_DIR = ".trash";
+export declare function createTrashFileTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/trash-file.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import { errorMessage } from '../../guards.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { localPathOf, resolveRooted, rootedLabel, stringArg } from '../fs/tool-path.js';
+export const TRASH_DIR = '.trash';
+export function createTrashFileTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'trash_file',
+        toolset: 'files',
+        description: `Move a file or folder to the shared folder's ${TRASH_DIR} folder, where the user can restore it. ` +
+            'Nothing is deleted permanently. Asks the user first.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to trash, relative to the shared folder' }
+            },
+            required: ['path']
+        },
+        effect: () => 'write',
+        autoApprove: false,
+        writeRootsRequired: true,
+        validate: (args) => (stringArg(args, 'path') ? null : 'path is required'),
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: rootedLabel('trash', { grants: ctx, paths: [String(args.path)] })
+        }),
+        async execute(args, ctx) {
+            const requested = String(args.path);
+            const resolved = await resolveRooted(requested, {
+                grants: ctx,
+                write: true,
+                realpath,
+                deniedRoots
+            });
+            if ('error' in resolved) {
+                return resolved;
+            }
+            const source = localPathOf(resolved);
+            if (!source || resolved.root.kind !== 'local') {
+                return { error: 'trash works only in a folder on this device' };
+            }
+            if (resolved.key === '/') {
+                return { error: 'the shared folder itself cannot be trashed' };
+            }
+            try {
+                if (!fs.existsSync(source)) {
+                    return { error: `no such file: ${requested}` };
+                }
+                const bin = path.join(resolved.root.root, TRASH_DIR);
+                const name = `${Date.now().toString(36)}-${path.basename(source)}`;
+                await fs.promises.mkdir(bin, { recursive: true });
+                await fs.promises.rename(source, path.join(bin, name));
+                return { trashed: requested, restorableAt: `${TRASH_DIR}/${name}` };
+            }
+            catch (err) {
+                return { error: errorMessage(err) };
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/files/write-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createWriteFileTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/write-file.js

@@ -0,0 +1,55 @@
+import { errorMessage } from '../../guards.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { existsNow, resolveRooted, rootedLabel, stringArg } from '../fs/tool-path.js';
+import { writeText } from '../fs/write.js';
+export function createWriteFileTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'write_file',
+        toolset: 'files',
+        description: 'Write a whole file in the shared folder: creates it (and its folders) or replaces it completely. ' +
+            'Replacing an existing file asks the user first. For a small change, use edit_file. ' +
+            'Use this, not exec, to write files in the shared folder.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path, relative to the shared folder' },
+                content: { type: 'string', description: 'The complete new content' }
+            },
+            required: ['path', 'content']
+        },
+        effect: (args, ctx) => (existsNow(stringArg(args, 'path'), ctx) ? 'write' : 'read'),
+        writeRootsRequired: true,
+        validate: (args) => stringArg(args, 'path') && typeof args.content === 'string'
+            ? null
+            : 'path and content are required',
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: `${rootedLabel('write', { grants: ctx, paths: [String(args.path)] })}, ${String(args.content ?? '').length} chars`
+        }),
+        async execute(args, ctx) {
+            const requested = String(args.path);
+            const resolved = await resolveRooted(requested, {
+                grants: ctx,
+                write: true,
+                realpath,
+                deniedRoots
+            });
+            if ('error' in resolved) {
+                return resolved;
+            }
+            try {
+                const existing = await resolved.root.drive.entry(resolved.key);
+                if (existing !== null && ctx?.approval === 'auto') {
+                    return { error: `${requested} already exists; call write_file again to replace it` };
+                }
+                await writeText(resolved.root.drive, resolved.key, String(args.content), {
+                    executable: existing?.value.executable
+                });
+                return { written: requested, replaced: existing !== null };
+            }
+            catch (err) {
+                return { error: errorMessage(err) };
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/fs/document-text.d.ts

@@ -0,0 +1,2 @@
+export declare function isDocument(key: string): boolean;
+export declare function documentText(key: string, bytes: Uint8Array): Promise<string>;

package/dist-lib/lib/tools/fs/document-text.js

@@ -0,0 +1,38 @@
+import { HarnessError } from '../../errors.js';
+import { docx, pptx } from '../../office/engine/index.js';
+let pdfium = null;
+function loadPdfium() {
+    pdfium ??= import('bare-pdfium').then((loaded) => loaded, () => null);
+    return pdfium;
+}
+export function isDocument(key) {
+    return /\.(pdf|docx|pptx)$/i.test(key);
+}
+export async function documentText(key, bytes) {
+    if (!/\.pdf$/i.test(key)) {
+        const read = /\.docx$/i.test(key) ? docx.open(bytes).read() : pptx.open(bytes).read();
+        return collectText(read).join('\n');
+    }
+    const lib = await loadPdfium();
+    if (!lib) {
+        throw new HarnessError('PDF_TEXT_UNAVAILABLE');
+    }
+    const doc = lib.open(bytes);
+    try {
+        return [...doc.textPages()]
+            .map(({ page, text }) => `--- page ${page + 1} ---\n${text.replace(/\r\n?/g, '\n').trim()}`)
+            .join('\n');
+    }
+    finally {
+        doc.close();
+    }
+}
+function collectText(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(collectText);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return [];
+    }
+    return Object.entries(value).flatMap(([key, inner]) => key === 'text' && typeof inner === 'string' ? [inner] : collectText(inner));
+}

package/dist-lib/lib/tools/fs/edit-match.d.ts

@@ -0,0 +1,11 @@
+export interface EditRequest {
+    readonly old: string;
+    readonly replacement: string;
+    readonly replaceAll: boolean;
+}
+export interface EditMatch {
+    content: string;
+    count: number;
+    error: string | null;
+}
+export declare function editMatch(content: string, request: EditRequest): EditMatch;

package/dist-lib/lib/tools/fs/edit-match.js

@@ -0,0 +1,85 @@
+const TYPOGRAPHIC = {
+    '“': '"',
+    '”': '"',
+    '‘': "'",
+    '’': "'",
+    '–': '-',
+    '—': '-',
+    ' ': ' '
+};
+function plain(text) {
+    return text.replace(/[“”‘’–— ]/g, (c) => TYPOGRAPHIC[c] ?? c);
+}
+function occurrences(haystack, needle) {
+    const found = [];
+    let at = haystack.indexOf(needle);
+    while (at !== -1) {
+        found.push({ from: at, to: at + needle.length });
+        at = haystack.indexOf(needle, at + needle.length);
+    }
+    return found;
+}
+function lineStarts(lines) {
+    const starts = [];
+    let offset = 0;
+    for (const line of lines) {
+        starts.push(offset);
+        offset += line.length + 1;
+    }
+    return starts;
+}
+function trimmedLineSpans(content, old) {
+    const lines = content.split('\n');
+    const wanted = old.split('\n').map((line) => line.trimEnd());
+    const ownsNewline = wanted.length > 1 && wanted[wanted.length - 1] === '';
+    if (ownsNewline) {
+        wanted.pop();
+    }
+    const starts = lineStarts(lines);
+    const spans = [];
+    for (let i = 0; i + wanted.length <= lines.length; i++) {
+        const block = lines.slice(i, i + wanted.length);
+        if (block.every((line, k) => line.trimEnd() === wanted[k])) {
+            const last = i + wanted.length - 1;
+            const end = starts[last] + lines[last].length;
+            spans.push({ from: starts[i], to: ownsNewline && last < lines.length - 1 ? end + 1 : end });
+        }
+    }
+    return spans;
+}
+function spansFor(content, old) {
+    const exact = occurrences(content, old);
+    if (exact.length) {
+        return exact;
+    }
+    const typographic = occurrences(plain(content), plain(old));
+    if (typographic.length) {
+        return typographic;
+    }
+    return trimmedLineSpans(plain(content), plain(old));
+}
+function ambiguity(text, spans) {
+    const lines = spans.map((span) => text.slice(0, span.from).split('\n').length).join(', ');
+    return `old text matches ${spans.length} places (lines ${lines}). Include a neighbouring line so it matches once, or set replaceAll to change every one.`;
+}
+export function editMatch(content, request) {
+    const crlf = content.includes('\r\n');
+    const text = crlf ? content.replace(/\r\n/g, '\n') : content;
+    const spans = spansFor(text, request.old.replace(/\r\n/g, '\n'));
+    if (!spans.length) {
+        return {
+            content,
+            count: 0,
+            error: 'old text not found. Read the file with read_file and copy the exact lines you want to change, including their indentation.'
+        };
+    }
+    if (spans.length > 1 && !request.replaceAll) {
+        return { content, count: 0, error: ambiguity(text, spans) };
+    }
+    const replacement = request.replacement.replace(/\r\n/g, '\n');
+    let next = text;
+    for (const span of [...spans].sort((a, b) => b.from - a.from)) {
+        next = next.slice(0, span.from) + replacement + next.slice(span.to);
+    }
+    return { content: crlf ? next.replace(/\n/g, '\r\n') : next, count: spans.length, error: null };
+}

package/dist-lib/lib/tools/fs/remote.d.ts

@@ -1,3 +1,4 @@
+import { HarnessError } from '../../errors.ts';
 import type { DriveRequest, DriveResponse } from './remote-protocol.ts';
 import type { HyperRoot } from './scope.ts';
 export interface GrantedDrive {
@@ -8,7 +9,7 @@ export type DriveOpFn = (request: DriveRequest) => Promise<DriveResponse>;
 export declare const DRIVE_CALL_TIMEOUT_MS = 20000;
 export declare const MAX_DRIVE_BYTES: number;
 export declare const DRIVE_LIST_PAGE = 256;
-export declare class DriveReadTruncatedError extends Error {
+export declare class DriveReadTruncatedError extends HarnessError<'DRIVE_READ_TRUNCATED'> {
     constructor(key: string);
 }
 export declare function isDriveReadTruncated(err: unknown): err is DriveReadTruncatedError;

package/dist-lib/lib/tools/fs/remote.js

@@ -1,15 +1,15 @@
 import fs from 'fs';
 import path from 'path';
 import { Writable } from 'streamx';
+import { HarnessError } from '../../errors.js';
 import { STAGING_DIR } from '../../staging.js';
 export const DRIVE_CALL_TIMEOUT_MS = 20_000;
 export const MAX_DRIVE_BYTES = 8 * 1024 * 1024;
 export const DRIVE_LIST_PAGE = 256;
 const noop = () => { };
-export class DriveReadTruncatedError extends Error {
+export class DriveReadTruncatedError extends HarnessError {
     constructor(key) {
-        super(`read stopped at ${MAX_DRIVE_BYTES} bytes: ${key}`);
-        this.name = 'DriveReadTruncatedError';
+        super('DRIVE_READ_TRUNCATED', [MAX_DRIVE_BYTES, key]);
     }
 }
 export function isDriveReadTruncated(err) {
@@ -17,7 +17,7 @@ export function isDriveReadTruncated(err) {
 }
 function withTimeout(promise, ms, op) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(`drive ${op} timed out`)), ms);
+        const timer = setTimeout(() => reject(new HarnessError('DRIVE_TIMED_OUT', [op])), ms);
         promise.then((value) => {
             clearTimeout(timer);
             resolve(value);

package/dist-lib/lib/tools/fs/scope.d.ts

@@ -22,7 +22,7 @@ export declare const NO_DIRS_GRANTED = "no directories are granted";
 export interface FsToolError {
     error: string;
 }
-export declare const NO_STORAGE_ROOT = "cannot fence the app storage root: the SDK home is unknown";
+export { NO_STORAGE_ROOT } from '../../errors.ts';
 export declare function deniedRootsFor(sdkHome: string | undefined): readonly string[];
 export declare const PROTECTED_PATH_ERROR = "path is inside a protected app directory";
 export declare function canonicalDenyRoots(deniedRoots: readonly string[] | undefined, realpath: Realpath): Promise<readonly string[]>;

package/dist-lib/lib/tools/fs/scope.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import process from 'process';
+import { HarnessError } from '../../errors.js';
 export const defaultRealpath = (p) => fs.promises.realpath(p);
 export const NO_DIRS_GRANTED = 'no directories are granted';
 const HYPER_PREFIX = 'hyper://';
@@ -10,10 +11,10 @@ function rootLabel(root) {
 function outside(roots) {
     return { error: `path must be inside one of: ${roots.map(rootLabel).join(', ')}` };
 }
-export const NO_STORAGE_ROOT = 'cannot fence the app storage root: the SDK home is unknown';
+export { NO_STORAGE_ROOT } from '../../errors.js';
 export function deniedRootsFor(sdkHome) {
     if (!sdkHome)
-        throw new Error(NO_STORAGE_ROOT);
+        throw new HarnessError('NO_STORAGE_ROOT');
     return [path.dirname(sdkHome)];
 }
 export const PROTECTED_PATH_ERROR = 'path is inside a protected app directory';

package/dist-lib/lib/tools/fs/targets.d.ts

@@ -0,0 +1,10 @@
+import { type DriveRoot, type FsToolError, type ResolveKeyOptions } from './scope.ts';
+export interface SearchTarget {
+    root: DriveRoot;
+    folder: string;
+}
+export interface ResolvedTargets {
+    targets: SearchTarget[];
+}
+export declare function searchTargets(dir: unknown, roots: readonly DriveRoot[], { realpath, deny }: ResolveKeyOptions): Promise<ResolvedTargets | FsToolError>;
+export declare function relativeKey(key: string, folder: string): string;

package/dist-lib/lib/tools/fs/targets.js

@@ -0,0 +1,32 @@
+import { NO_DIRS_GRANTED, resolveKey } from './scope.js';
+export async function searchTargets(dir, roots, { realpath, deny }) {
+    if (typeof dir === 'string' && dir.trim()) {
+        const resolved = await resolveKey(dir, roots, { realpath, deny });
+        if ('error' in resolved) {
+            return resolved;
+        }
+        if (resolved.root.kind === 'local') {
+            if (!resolved.exists) {
+                return { error: `no such file: ${dir}` };
+            }
+        }
+        else {
+            let hasEntry = false;
+            for await (const _entry of resolved.root.drive.list(resolved.key)) {
+                hasEntry = true;
+                break;
+            }
+            if (!hasEntry && (await resolved.root.drive.entry(resolved.key)) === null) {
+                return { error: `no such file: ${dir}` };
+            }
+        }
+        return { targets: [{ root: resolved.root, folder: resolved.key }] };
+    }
+    if (roots.length === 0) {
+        return { error: NO_DIRS_GRANTED };
+    }
+    return { targets: roots.map((root) => ({ root, folder: '/' })) };
+}
+export function relativeKey(key, folder) {
+    return folder === '/' ? key.slice(1) : key.slice(folder.length + 1);
+}

package/dist-lib/lib/tools/fs/tool-path.d.ts

@@ -0,0 +1,24 @@
+import { type DriveRoot, type FsToolError, type Realpath, type ResolvedKey } from './scope.ts';
+export interface Grants {
+    readonly fsRoots?: readonly DriveRoot[] | undefined;
+    readonly fsWriteRoots?: readonly DriveRoot[] | undefined;
+}
+export declare function anchorOf(grants: Grants | undefined): DriveRoot | undefined;
+export declare function rootedPath(p: string, anchor: DriveRoot | undefined): string;
+export declare function shownPath(full: string, anchor: DriveRoot | undefined): string;
+export interface RootedScope {
+    readonly grants: Grants | undefined;
+    readonly write: boolean;
+    readonly realpath: Realpath;
+    readonly deniedRoots?: readonly string[] | undefined;
+}
+export declare function resolveRooted(p: string, { grants, write, realpath, deniedRoots }: RootedScope): Promise<ResolvedKey | FsToolError>;
+export declare function stringArg(args: Record<string, unknown>, key: string): string | null;
+export declare function positiveInt(value: unknown): number | undefined;
+export declare function existsNow(p: string | null, grants: Grants | undefined): boolean;
+export interface LabelPaths {
+    readonly grants: Grants | undefined;
+    readonly paths: readonly string[];
+}
+export declare function rootedLabel(verb: string, { grants, paths }: LabelPaths): string;
+export declare function localPathOf(resolved: ResolvedKey): string | null;

package/dist-lib/lib/tools/fs/tool-path.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import path from 'path';
+import { canonicalDenyRoots, hostPath, resolveKey } from './scope.js';
+const HYPER_PREFIX = 'hyper://';
+export function anchorOf(grants) {
+    return grants?.fsRoots?.[0] ?? grants?.fsWriteRoots?.[0];
+}
+function baseOf(root) {
+    return root.kind === 'local' ? root.root : `${HYPER_PREFIX}${root.key}`;
+}
+export function rootedPath(p, anchor) {
+    if (!anchor || p.startsWith(HYPER_PREFIX) || path.isAbsolute(p) || p.startsWith('~')) {
+        return p;
+    }
+    if (anchor.kind === 'local') {
+        return path.join(anchor.root, p);
+    }
+    const prefix = anchor.prefix === '/' ? '' : anchor.prefix;
+    return `${HYPER_PREFIX}${anchor.key}${prefix}/${p.replace(/^\.?\//, '')}`;
+}
+export function shownPath(full, anchor) {
+    if (!anchor) {
+        return full;
+    }
+    const base = baseOf(anchor);
+    if (full === base) {
+        return '.';
+    }
+    return full.startsWith(base + '/') ? full.slice(base.length + 1) : full;
+}
+export async function resolveRooted(p, { grants, write, realpath, deniedRoots }) {
+    const roots = (write ? grants?.fsWriteRoots : grants?.fsRoots) ?? [];
+    const deny = await canonicalDenyRoots(deniedRoots, realpath);
+    return resolveKey(rootedPath(p, anchorOf(grants)), roots, { realpath, deny });
+}
+export function stringArg(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+export function positiveInt(value) {
+    const n = Number(value);
+    return value === undefined || value === null || !Number.isInteger(n) || n < 1 ? undefined : n;
+}
+export function existsNow(p, grants) {
+    const anchor = anchorOf(grants);
+    if (!p || !anchor || anchor.kind !== 'local') {
+        return true;
+    }
+    const target = rootedPath(p, anchor);
+    return !path.isAbsolute(target) || fs.existsSync(target);
+}
+export function rootedLabel(verb, { grants, paths }) {
+    const anchor = anchorOf(grants);
+    return `${verb} ${paths.map((p) => rootedPath(p, anchor)).join(' → ')}`;
+}
+export function localPathOf(resolved) {
+    return resolved.root.kind === 'local' ? hostPath(resolved.root, resolved.key) : null;
+}