@meistrari/tela-cli 1.0.0 → 1.2.0

package/dist/commands/skills.d.ts

@@ -0,0 +1,33 @@
+import type { PantrySkillManifestEntry, PantrySkillSummary } from '@meistrari/tela-pantry';
+import type { InstalledSkill } from '@meistrari/tela-local-config';
+import type { CliIo, GlobalOptions } from '../output';
+export declare function runSkillsCommand(args: string[], options: GlobalOptions, io: CliIo): Promise<number>;
+type SkillListEntry = PantrySkillSummary & {
+    installed: boolean;
+    installedSha: string | null;
+    /** Installed, but Pantry has since published a different snapshot. */
+    outdated: boolean;
+};
+export declare function annotateInstalled(skills: readonly PantrySkillSummary[], installed: readonly InstalledSkill[]): SkillListEntry[];
+export declare function formatSkillList(entries: readonly SkillListEntry[]): string[];
+export declare function formatManifestTree(entries: readonly PantrySkillManifestEntry[]): string[];
+export declare function formatBytes(size: number): string;
+/**
+ * No slugs means every installed skill: upgrading is additive, and "all of
+ * them" is the only reading of a bare `skills upgrade`.
+ *
+ * A named slug the registry does not know is refused for the whole command
+ * rather than skipped, so a typo among several cannot leave some skills
+ * upgraded and report success.
+ */
+export declare function selectUpgradeTargets(installed: readonly InstalledSkill[], slugs: readonly string[]): InstalledSkill[];
+/**
+ * Is this the same installation, rather than one that replaced it?
+ *
+ * `slug` and `dir` are both derived from the slug, so neither moves across a
+ * reinstall; `installedAt` and `sha` are what actually distinguish one install
+ * from the next.
+ */
+export declare function isSameInstall(left: InstalledSkill, right: InstalledSkill): boolean;
+export declare function scriptFailureMessage(entry: Pick<InstalledSkill, 'slug' | 'dir'>, phase: 'install' | 'uninstall'): string;
+export {};

package/dist/commands/skills.js

@@ -0,0 +1,519 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkillsCommand = runSkillsCommand;
+exports.annotateInstalled = annotateInstalled;
+exports.formatSkillList = formatSkillList;
+exports.formatManifestTree = formatManifestTree;
+exports.formatBytes = formatBytes;
+exports.selectUpgradeTargets = selectUpgradeTargets;
+exports.isSameInstall = isSameInstall;
+exports.scriptFailureMessage = scriptFailureMessage;
+const promises_1 = require("node:fs/promises");
+const tela_pantry_1 = require("@meistrari/tela-pantry");
+const tela_local_config_1 = require("@meistrari/tela-local-config");
+const markdown_1 = require("../markdown");
+const output_1 = require("../output");
+const session_1 = require("../session");
+const skills_1 = require("../skills");
+async function runSkillsCommand(args, options, io) {
+    const [command, ...rest] = args;
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        writeSkillsHelp(io);
+        return 0;
+    }
+    try {
+        if (command === 'list')
+            return await listSkills(rest, options, io);
+        if (command === 'search')
+            return await searchSkills(rest, options, io);
+        if (command === 'files')
+            return await showSkillFiles(rest, options, io);
+        if (command === 'cat')
+            return await catSkillFile(rest, options, io);
+        if (command === 'install')
+            return await installSkills(rest, options, io);
+        if (command === 'upgrade')
+            return await upgradeSkills(rest, options, io);
+        if (command === 'uninstall')
+            return await uninstallSkills(rest, options, io);
+        return usageError(`Unknown skills command: ${command}`, io);
+    }
+    catch (error) {
+        (0, output_1.writeError)(io, formatError(error));
+        return 1;
+    }
+}
+/**
+ * `list` and `search` are the same listing, and Pantry applies the free-text
+ * filter itself — so the only difference is whether a query is passed.
+ */
+async function listSkills(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length > 0)
+        return usageError(`Unknown skills list argument: ${flags.rest[0]}`, io);
+    return await writeCatalog(flags, options, io, {});
+}
+async function searchSkills(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [query, ...extra] = flags.rest;
+    if (!query)
+        return usageError('Usage: tela skills search <query> [--json]', io);
+    if (extra.length > 0)
+        return usageError(`Unknown skills search argument: ${extra[0]}`, io);
+    return await writeCatalog(flags, options, io, { query });
+}
+async function writeCatalog(flags, options, io, filters) {
+    const { client } = await (0, session_1.loadPantry)(flags);
+    const [skills, installed] = await Promise.all([
+        (0, tela_pantry_1.fetchSkillCatalog)(client, filters),
+        (0, tela_local_config_1.listInstalledSkills)(),
+    ]);
+    const entries = annotateInstalled(skills, installed);
+    if (options.json) {
+        (0, output_1.writeJson)(io, { skills: entries });
+        return 0;
+    }
+    if (entries.length === 0) {
+        (0, output_1.writeLine)(io, '(no skills found)');
+        return 0;
+    }
+    for (const line of formatSkillList(entries))
+        (0, output_1.writeLine)(io, line);
+    return 0;
+}
+function annotateInstalled(skills, installed) {
+    const bySlug = new Map(installed.map(entry => [entry.slug, entry]));
+    return skills.map((skill) => {
+        const entry = bySlug.get(skill.slug);
+        return {
+            ...skill,
+            installed: entry !== undefined,
+            installedSha: entry?.sha ?? null,
+            // Only claim staleness when both shas are known: a skill Pantry has
+            // not snapshotted yet is not an outdated install.
+            outdated: entry !== undefined
+                && skill.snapshotSha !== null
+                && skill.snapshotSha !== entry.sha,
+        };
+    });
+}
+function formatSkillList(entries) {
+    const width = Math.max(...entries.map(entry => entry.slug.length));
+    return entries.map((entry) => {
+        // `↑` over `✓` for an install Pantry has moved past, so `skills list`
+        // answers "what should I upgrade?" on its own.
+        const marker = entry.outdated ? '↑ ' : entry.installed ? '✓ ' : '  ';
+        return `${marker}${entry.slug.padEnd(width)}  ${entry.description}`;
+    });
+}
+async function showSkillFiles(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela skills files <slug> [--json]', io);
+    const { client } = await (0, session_1.loadPantry)(flags);
+    const { snapshot } = await (0, tela_pantry_1.fetchSkillFile)(client, slug);
+    if (options.json) {
+        (0, output_1.writeJson)(io, { slug, sha: snapshot.sha, entries: snapshot.manifest.entries });
+        return 0;
+    }
+    for (const line of formatManifestTree(snapshot.manifest.entries))
+        (0, output_1.writeLine)(io, line);
+    return 0;
+}
+function formatManifestTree(entries) {
+    if (entries.length === 0)
+        return ['(no files)'];
+    return [...entries]
+        .sort((left, right) => left.path.localeCompare(right.path))
+        .map((entry) => {
+        const segments = entry.path.split('/');
+        const indent = '  '.repeat(segments.length - 1);
+        const name = segments[segments.length - 1] ?? entry.path;
+        return entry.kind === 'directory'
+            ? `${indent}${name}/`
+            : `${indent}${name}  ${formatBytes(entry.size)}`;
+    });
+}
+function formatBytes(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function catSkillFile(args, _options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const [slug, filePath] = flags.rest;
+    if (!slug)
+        return usageError('Usage: tela skills cat <slug> [path]', io);
+    const { client } = await (0, session_1.loadPantry)(flags);
+    const { file } = await (0, tela_pantry_1.fetchSkillFile)(client, slug, filePath);
+    if (file.content === null) {
+        return usageError(`${file.path} is not previewable (${file.size} bytes, ${file.mediaType ?? 'unknown type'}).\n`
+            + `Download it directly: ${file.downloadUrl}`, io);
+    }
+    // Markdown is rendered for a terminal and passed through untouched for a
+    // pipe; anything else is already plain text.
+    (0, output_1.writeLine)(io, file.mediaType === 'text/markdown' ? await (0, markdown_1.renderMarkdown)(file.content) : file.content);
+    return 0;
+}
+async function installSkills(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length === 0)
+        return usageError('Usage: tela skills install <slug...> [--force] [--no-symlink] [--ignore-scripts]', io);
+    // Every slug is validated before any of them is installed: one bad slug
+    // among several must stop the command before the safe ones are already on
+    // disk, and before an unvalidated slug reaches a request path.
+    for (const slug of flags.rest)
+        (0, skills_1.assertSafeSlug)(slug, 'install');
+    const pantry = await (0, session_1.loadPantry)(flags);
+    const installed = [];
+    for (const slug of flags.rest) {
+        const entry = await installOne(pantry, slug, flags, io);
+        if (entry)
+            installed.push(entry);
+    }
+    if (options.json) {
+        (0, output_1.writeJson)(io, { installed });
+        return 0;
+    }
+    for (const entry of installed)
+        (0, output_1.writeLine)(io, `Installed ${entry.slug}@${entry.sha.slice(0, 7)} to ${entry.dir}`);
+    return 0;
+}
+async function installOne(pantry, slug, flags, io, expectedCurrent) {
+    const roots = (0, skills_1.resolveSkillRoots)();
+    const target = (0, skills_1.resolveInstallDir)(roots, slug);
+    const { ingredient, snapshot } = await (0, tela_pantry_1.fetchSkillFile)(pantry.client, slug);
+    // Verified before anything is written: the order is the security property.
+    // Nothing is removed from disk until every file in the archive has been
+    // checked against the manifest, so a tampered or truncated download can
+    // never delete a working install. Downloading outside the lock also keeps
+    // the network round-trip out of the critical section.
+    const files = (0, tela_pantry_1.verifySnapshotFiles)((0, tela_pantry_1.parseTarGz)(await (0, tela_pantry_1.downloadSkillArchive)(snapshot.archiveUrl)), snapshot.manifest);
+    const stagedInstalls = [];
+    let skippedReason = null;
+    let entry = null;
+    try {
+        entry = await (0, tela_local_config_1.updateInstalledSkill)(slug, async (registered) => {
+            if (expectedCurrent && (registered === null || !isSameInstall(registered, expectedCurrent))) {
+                skippedReason = `Skipped ${slug}: it was changed while this upgrade ran`;
+                return registered;
+            }
+            // Re-checked against the registry as it stands inside the lock. Read
+            // before acquiring it, this guard would answer for a moment that has
+            // passed by the time the files are written.
+            //
+            // An upgrade needs no exemption here: the entry it is upgrading names
+            // this very directory, so the guard already recognises it as ours.
+            if ((0, skills_1.isUnownedInstallDir)(target, registered?.dir ?? null) && !flags.force) {
+                throw new Error(`${target} already exists and was not installed by tela.\n`
+                    + `Run \`tela skills install ${slug} --force\` to replace it, or remove it by hand.`);
+            }
+            const staged = await (0, skills_1.stageSkillFiles)(target, files);
+            stagedInstalls.push(staged);
+            const link = flags.symlink
+                ? await (0, skills_1.linkSkill)(roots, slug, target, flags.force)
+                : await removeRecordedSymlinks(registered?.symlinks ?? [], target, io);
+            if (link.skipped)
+                (0, output_1.writeError)(io, `Skipped symlink: ${link.skipped}`);
+            return {
+                slug,
+                dir: target,
+                sha: snapshot.sha,
+                bundle: ingredient.bundle,
+                symlinks: link.linked,
+                scripts: ingredient.scripts,
+                installedAt: new Date().toISOString(),
+            };
+        });
+    }
+    catch (error) {
+        await rollbackStagedInstall(stagedInstalls.at(-1) ?? null, error);
+    }
+    if (skippedReason) {
+        (0, output_1.writeError)(io, skippedReason);
+        return null;
+    }
+    for (const staged of stagedInstalls)
+        await staged.commit();
+    if (!entry)
+        return null;
+    // Outside the lock on purpose: the script is arbitrary shell from the
+    // catalog and may run for as long as it likes, which is exactly what must
+    // not happen while every other tela process waits on the inventory.
+    //
+    // That leaves a window, knowingly: a concurrent install of the same slug
+    // can replace this directory once the lock is released, and this script
+    // would then run against the newer install's files. Reaching it takes two
+    // tela processes on one slug, overlapping, a skill that declares an install
+    // script, and two snapshots whose scripts differ enough for the older to do
+    // damage. Guarding it was tried and reverted: the check costs a registry
+    // read on every install to catch only the case where the replacement has
+    // already finished, and a replacement landing mid-script is undetectable
+    // without holding the lock across arbitrary shell — which the refresh now
+    // sustains for as long as the script runs, so every other tela process
+    // would wait behind it instead of the lock ageing out.
+    await runLifecycleScript(entry, 'install', flags.ignoreScripts, io);
+    return entry;
+}
+async function removeRecordedSymlinks(symlinks, target, io) {
+    for (const linkPath of symlinks) {
+        const outcome = await (0, skills_1.removeManagedSymlink)(linkPath, target);
+        if (outcome.reason)
+            (0, output_1.writeError)(io, outcome.reason);
+    }
+    return { linked: [], skipped: null };
+}
+async function rollbackStagedInstall(staged, error) {
+    if (!staged)
+        throw error;
+    try {
+        await staged.rollback();
+    }
+    catch (cleanupError) {
+        throw new Error(`${formatError(error)}\nCleanup failed: ${formatError(cleanupError)}`);
+    }
+    throw error;
+}
+/**
+ * No slugs means every installed skill: upgrading is additive, and "all of
+ * them" is the only reading of a bare `skills upgrade`.
+ *
+ * A named slug the registry does not know is refused for the whole command
+ * rather than skipped, so a typo among several cannot leave some skills
+ * upgraded and report success.
+ */
+function selectUpgradeTargets(installed, slugs) {
+    if (slugs.length === 0)
+        return [...installed];
+    const bySlug = new Map(installed.map(entry => [entry.slug, entry]));
+    const missing = slugs.filter(slug => !bySlug.has(slug));
+    if (missing.length > 0)
+        throw new Error(`${missing.join(', ')} not installed by tela. Nothing to upgrade.`);
+    return slugs.map(slug => bySlug.get(slug));
+}
+async function upgradeSkills(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    const targets = selectUpgradeTargets(await (0, tela_local_config_1.listInstalledSkills)(), flags.rest);
+    if (targets.length === 0) {
+        if (options.json)
+            (0, output_1.writeJson)(io, { upgraded: [], unchanged: [] });
+        else
+            (0, output_1.writeLine)(io, 'No skills installed.');
+        return 0;
+    }
+    const pantry = await (0, session_1.loadPantry)(flags);
+    const upgraded = [];
+    const unchanged = [];
+    for (const entry of targets) {
+        const { snapshot } = await (0, tela_pantry_1.fetchSkillFile)(pantry.client, entry.slug);
+        // Same snapshot means the same bytes: reinstalling would re-run the
+        // install script for no change.
+        if (snapshot.sha === entry.sha) {
+            unchanged.push(entry.slug);
+            continue;
+        }
+        // `flags` as the user gave them. Synthesising `force: true` here would
+        // reach past the install directory the upgrade owns and into the link
+        // path, where a directory another tool put there would be deleted.
+        const upgradedEntry = await installOne(pantry, entry.slug, flags, io, entry);
+        if (upgradedEntry)
+            upgraded.push(upgradedEntry);
+    }
+    if (options.json) {
+        (0, output_1.writeJson)(io, { upgraded, unchanged });
+        return 0;
+    }
+    for (const entry of upgraded)
+        (0, output_1.writeLine)(io, `Upgraded ${entry.slug} to ${entry.sha.slice(0, 7)}`);
+    for (const slug of unchanged)
+        (0, output_1.writeLine)(io, `${slug} is already up to date`);
+    return 0;
+}
+async function uninstallSkills(args, options, io) {
+    const flags = parseSkillFlags(args);
+    if ('error' in flags)
+        return usageError(flags.error, io);
+    if (flags.rest.length === 0)
+        return usageError('Usage: tela skills uninstall <slug...> [--ignore-scripts]', io);
+    const installed = await (0, tela_local_config_1.listInstalledSkills)();
+    const bySlug = new Map(installed.map(entry => [entry.slug, entry]));
+    const missing = flags.rest.filter(slug => !bySlug.has(slug));
+    // Refused before anything is deleted rather than skipped over: with several
+    // slugs, removing the ones that resolved and ignoring a typo leaves a
+    // partial uninstall behind a success exit code.
+    if (missing.length > 0)
+        return usageError(`${missing.join(', ')} not installed by tela. Nothing to remove.`, io);
+    const removed = [];
+    const roots = (0, skills_1.resolveSkillRoots)();
+    for (const slug of flags.rest) {
+        // Registry-driven: an unregistered slug never reaches this loop, so a
+        // recursive delete can only ever be pointed at a directory tela
+        // recorded writing.
+        const entry = bySlug.get(slug);
+        if (!entry)
+            continue;
+        assertManagedInstallDir(slug, entry, roots);
+        // Before the lock: the script is arbitrary shell, it runs in the
+        // directory about to be deleted, and holding the inventory for its
+        // duration would block every other tela process.
+        await runLifecycleScript(entry, 'uninstall', flags.ignoreScripts, io);
+        let gone = false;
+        await (0, tela_local_config_1.updateInstalledSkill)(slug, async (registered) => {
+            // The entry read before the script ran may be stale: a concurrent
+            // uninstall already finished, or a concurrent install replaced it.
+            if (registered === null)
+                return null;
+            // Compared whole rather than by `dir`, which is derived from the
+            // slug and so is the same string for a reinstall — it cannot tell
+            // "still the entry whose script just ran" from "someone reinstalled
+            // while it ran". A reinstall carries a fresh `installedAt`, and an
+            // entry matching in every field describes the same sha recorded at
+            // the same instant, which this uninstall is entitled to remove.
+            if (!isSameInstall(registered, entry)) {
+                (0, output_1.writeError)(io, `Skipped ${slug}: it was reinstalled while this uninstall ran`);
+                return registered;
+            }
+            assertManagedInstallDir(slug, registered, roots);
+            for (const linkPath of registered.symlinks) {
+                const outcome = await (0, skills_1.removeManagedSymlink)(linkPath, registered.dir);
+                if (outcome.reason)
+                    (0, output_1.writeError)(io, outcome.reason);
+            }
+            await (0, promises_1.rm)(registered.dir, { recursive: true, force: true });
+            gone = true;
+            return null;
+        });
+        if (gone)
+            removed.push(slug);
+    }
+    if (options.json) {
+        (0, output_1.writeJson)(io, { removed });
+        return 0;
+    }
+    for (const slug of removed)
+        (0, output_1.writeLine)(io, `Removed ${slug}`);
+    return 0;
+}
+function assertManagedInstallDir(slug, entry, roots) {
+    const expectedDir = (0, skills_1.resolveInstallDir)(roots, slug);
+    if (entry.slug !== slug || entry.dir !== expectedDir) {
+        throw new Error(`${slug} is recorded at ${entry.dir}, not the managed install directory ${expectedDir}. `
+            + 'Refusing to remove it.');
+    }
+}
+/**
+ * Is this the same installation, rather than one that replaced it?
+ *
+ * `slug` and `dir` are both derived from the slug, so neither moves across a
+ * reinstall; `installedAt` and `sha` are what actually distinguish one install
+ * from the next.
+ */
+function isSameInstall(left, right) {
+    return left.installedAt === right.installedAt
+        && left.sha === right.sha
+        && left.dir === right.dir;
+}
+/**
+ * Run a skill's install or uninstall script, unless asked not to.
+ *
+ * A failing install script does not undo the install: by the time it runs the
+ * files are already on disk, and dropping the registry entry would strand a
+ * directory `uninstall` could no longer be pointed at. The failure is reported
+ * and the command exits non-zero instead.
+ */
+async function runLifecycleScript(entry, phase, ignoreScripts, io) {
+    const script = entry.scripts?.[phase];
+    if (!script)
+        return;
+    if (ignoreScripts) {
+        (0, output_1.writeError)(io, `Skipped ${phase} script for ${entry.slug}: ${script}`);
+        return;
+    }
+    (0, output_1.writeError)(io, `Running ${phase} script for ${entry.slug}: ${script}`);
+    const outcome = await (0, skills_1.runSkillScript)(script, entry.dir);
+    if (outcome.output)
+        (0, output_1.writeError)(io, outcome.output);
+    if (!outcome.ok)
+        throw new Error(scriptFailureMessage(entry, phase));
+}
+function scriptFailureMessage(entry, phase) {
+    const opener = `${phase} script failed for ${entry.slug}.`;
+    if (phase === 'uninstall')
+        return `${opener}\n${entry.slug} was left in place. Re-run with --ignore-scripts to remove it anyway.`;
+    return `${opener}\n`
+        + `${entry.slug} was installed to ${entry.dir} and recorded, but its install script did not `
+        + 'finish, so the skill may not work.\n'
+        + `Remove it with \`tela skills uninstall ${entry.slug}\`, or reinstall without the script: `
+        + `\`tela skills install ${entry.slug} --ignore-scripts\`.`;
+}
+function parseSkillFlags(args) {
+    const flags = { force: false, symlink: true, ignoreScripts: false, rest: [] };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--context' || arg === '--environment' || arg === '--auth-env') {
+            const value = args[index + 1];
+            if (!value)
+                return { error: `Expected value after ${arg}` };
+            if (arg === '--context')
+                flags.contextId = value;
+            else
+                flags.environmentId = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--force' || arg === '-f') {
+            flags.force = true;
+            continue;
+        }
+        if (arg === '--no-symlink') {
+            flags.symlink = false;
+            continue;
+        }
+        if (arg === '--ignore-scripts') {
+            flags.ignoreScripts = true;
+            continue;
+        }
+        if (arg === '--json')
+            continue;
+        if (arg.startsWith('-'))
+            return { error: `Unknown skills option: ${arg}` };
+        flags.rest.push(arg);
+    }
+    return flags;
+}
+function usageError(message, io) {
+    (0, output_1.writeError)(io, message);
+    return 1;
+}
+function writeSkillsHelp(io) {
+    (0, output_1.writeLine)(io, 'Usage: tela skills <command> [args]');
+    (0, output_1.writeLine)(io);
+    (0, output_1.writeLine)(io, 'Commands:');
+    (0, output_1.writeLine)(io, '  skills list [--json]');
+    (0, output_1.writeLine)(io, '  skills search <query> [--json]');
+    (0, output_1.writeLine)(io, '  skills files <slug> [--json]');
+    (0, output_1.writeLine)(io, '  skills cat <slug> [path]');
+    (0, output_1.writeLine)(io, '  skills install <slug...> [-f|--force] [--no-symlink] [--ignore-scripts] [--json]');
+    (0, output_1.writeLine)(io, '  skills upgrade [slug...] [--ignore-scripts] [--json]');
+    (0, output_1.writeLine)(io, '  skills uninstall <slug...> [--ignore-scripts] [--json]');
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/docs/workflow-code/api-reference.md

@@ -14,6 +14,7 @@ import {
     build,
     canvas,
     code,
+    crop,
     input,
     llm,
     splitter,
@@ -32,6 +33,8 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`input.file()`](#inputfileoptions) | File input supplied by upload or Vault reference. |
 | [`llm()`](#llmoptions) | Single model-call transformation with optional structured output. |
 | [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
+| [`crop()`](#cropoptions) | Cropping selected PDF pages from compatible files or existing Vault files. |
+| [`vault.asset()`](#vaultassetpath-options) | Declaring a local file that `sync` uploads and locks in Vault. |
 | [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
 | [`remote()`](#remote) | Generated catalog paths and explicit ID refs for inert remote authoring. |
 | [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
@@ -390,7 +393,7 @@ type SplitterOptions = {
 function splitter(options: SplitterOptions): SplitterNodeHandle
 ```
 
-Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()`, or an array of Vault refs. It does not accept arbitrary strings or text references.
+Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()` or `vault.asset()`, or an array containing one of those Vault declaration kinds. It does not accept arbitrary strings or text references.
 
 | Option | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
@@ -471,6 +474,82 @@ const generatedCodePages = splitter({
 
 The referenced runtime value still needs to describe a real file. Declaring `fileUrl` or `vaultReference` in an LLM schema does not upload or create a Vault file.
 
+### `crop(options)`
+
+```ts
+type CropOptions = {
+    name: string
+    key?: string
+    input: {
+        file: WorkflowCodeExclusiveFileSource
+        indexes: readonly (number | string)[]
+        type?: 'pdf'
+    }
+}
+
+function crop(options: CropOptions): CropNodeHandle
+```
+
+Declares Workflow V3's existing `document-cropper` action. Its exclusive `input.file` supports the same compatible workflow input, prior-node output, `vault.ref()`, `vault.asset()`, and Vault-array forms as `splitter.input.file`.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Display name and fallback node identity. |
+| `key` | `string` | No | `name` | Stable identity when the display name may change. |
+| `input.file` | `WorkflowCodeExclusiveFileSource` | Yes | — | File/File-array workflow reference, `vault.ref()`, `vault.asset()`, or an array of Vault declarations. |
+| `input.indexes` | `readonly (number \| string)[]` | Yes | — | Integer page indexes or cropper-supported ranges such as `'3-5'`. |
+| `input.type` | `'pdf'` | No | `'pdf'` | Cropper document type. |
+
+```ts
+const selectedPages = crop({
+    name: 'Crop selected invoice pages',
+    input: {
+        file: ({ ref }) => ref(invoice),
+        indexes: [1, '3-5'],
+    },
+})
+
+const cropAgain = crop({
+    name: 'Crop prior result',
+    input: {
+        file: ({ ref, paths }) => ref(selectedPages, paths(selectedPages)[0].file),
+        indexes: [2],
+    },
+})
+```
+
+The result is a typed array whose items contain `indexes`, `originalFile`, and `file`. Compile validates file compatibility before lowering input and previous-node refs to Workflow V3 URIs; direct Vault refs lower to the cropper's transport-file shape. Source evaluation and offline compilation do not contact Vault or invoke prior nodes.
+
+### `vault.asset(path, options?)`
+
+```ts
+const vault: {
+    asset: (
+        path: string,
+        options?: { name?: string, mimeType?: string },
+    ) => WorkflowCodeVaultAsset
+}
+```
+
+Creates an inert declaration for a local file that should be available to `splitter()` or `crop()`. Source evaluation and offline compile do not read the file, upload it, or require credentials. `sync` resolves the path relative to `workflow-code.config.ts`, rejects paths outside that project directory, hashes the content, and uploads it before the first workflow lifecycle mutation. A matching content hash in the active context lock reuses the existing Vault ref.
+
+```ts
+const localInvoice = vault.asset('./fixtures/invoice.pdf', {
+    name: 'invoice.pdf',
+    mimeType: 'application/pdf',
+})
+
+const selectedPages = crop({
+    name: 'Crop local invoice',
+    input: {
+        file: localInvoice,
+        indexes: [1, '3-5'],
+    },
+})
+```
+
+`path`, `name`, and `mimeType` must be non-empty strings when present. Offline compile without a matching explicit asset snapshot reports `vault.asset.missing_lock`; it never falls back to reading the local file. If the file changes, the next `sync` uploads the new content and updates the lock.
+
 ### `vault.ref(reference)`
 
 ```ts
@@ -494,7 +573,7 @@ const existingPages = splitter({
 })
 ```
 
-During compile, a direct Vault ref used by `splitter.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
+During compile, a direct Vault ref used by `splitter.input.file` or `crop.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
 
 ### `agent(remoteRef, options)`
 

package/dist/docs/workflow-code/manifest.json

@@ -14,7 +14,7 @@
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "2306f6a21d23b4e3457262c3105e65e0292af5a59154aa15cf24188409db07f8"
+      "sha256": "fc121fd8c0e83e4f39ecef45b50d4fc9b0bc64888bd10d0590b3ca168af0a42d"
     },
     {
       "slug": "cli",