@meistrari/tela-cli 1.8.0 → 1.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Tela command line tools for local state and agent workflows.",
   "engines": {
     "node": ">=22"

package/dist/skills.d.ts

@@ -1,87 +0,0 @@
-import type { SkillFileContent } from '@meistrari/tela-pantry';
-export type SkillRoots = {
-    /** Where the skill's files actually live. */
-    installRoot: string;
-    /** Where a symlink back to the install directory is created. */
-    linkRoot: string;
-};
-export type StagedSkillFiles = {
-    commit: () => Promise<void>;
-    rollback: () => Promise<void>;
-};
-/**
- * One real copy under `~/.agents/skills`, symlinked into `~/.claude/skills`.
- *
- * Agent tooling reads a fixed pair of locations, so there is nowhere else worth
- * installing to; the roots stay parameterised only so tests can work inside a
- * temporary home.
- */
-export declare function resolveSkillRoots(home?: string): SkillRoots;
-/**
- * A slug reaches `path.join` and, eventually, a recursive delete. `path.join`
- * collapses `..`, so validation has to happen before the join — and both
- * clauses are needed: `isSafeSkillPath` is an archive-path predicate that
- * accepts `a/b`, which as a slug is a traversal into a sibling directory.
- */
-export declare function assertSafeSlug(slug: string, action: string): void;
-export declare function resolveInstallDir(roots: SkillRoots, slug: string): string;
-/**
- * The install guard: is something already sitting at the target that this CLI
- * did not put there?
- *
- * Compares the *recorded directory* rather than asking whether the slug is
- * registered at all. A registration pointing somewhere else is not permission
- * to replace what is at this path — which may be a directory the user created
- * by hand, or one another tool owns.
- */
-export declare function isUnownedInstallDir(target: string, registeredDir: string | null): boolean;
-/**
- * Write the verified files to `target`, replacing whatever is there.
- *
- * Nothing is deleted while the target is at risk. Everything is extracted to a
- * staging directory first, the previous install is renamed aside, the staged
- * copy is renamed in, and only then is the old copy dropped. Every destructive
- * step is a rename — which either happens or does not — and each has an
- * inverse, so an interrupted install can never leave a half-written skill where
- * a working one used to be.
- */
-export declare function materializeSkillFiles(target: string, files: readonly SkillFileContent[]): Promise<void>;
-export declare function stageSkillFiles(target: string, files: readonly SkillFileContent[]): Promise<StagedSkillFiles>;
-export type LinkOutcome = {
-    linked: string[];
-    /** Set when linking was skipped, explaining what is in the way. */
-    skipped: string | null;
-};
-/**
- * Symlink the install directory into the link root.
- *
- * A real directory already at the link path is left alone unless `force` says
- * otherwise: it is something another tool or the user put there, and replacing
- * it silently would delete files this CLI never wrote. A symlink pointing
- * somewhere other than the install directory gets the same treatment.
- */
-export declare function linkSkill(roots: SkillRoots, slug: string, target: string, force: boolean): Promise<LinkOutcome>;
-/**
- * Remove a symlink this CLI created that still points at the install directory.
- *
- * Every other case is reported and skipped. The link may since have been
- * replaced by a real directory belonging to something else, and uninstalling a
- * skill is not licence to delete it.
- */
-export declare function removeManagedSymlink(linkPath: string, target: string): Promise<{
-    removed: boolean;
-    reason: string | null;
-}>;
-export type ScriptOutcome = {
-    ok: boolean;
-    output: string;
-};
-/**
- * Run a skill's declared install or uninstall script, in the skill's own
- * directory.
- *
- * Both streams are captured and handed back rather than inherited: the script
- * is arbitrary shell from the catalog, and letting it write to stdout would
- * corrupt `--json` output. The caller relays them as diagnostics on stderr.
- */
-export declare function runSkillScript(script: string, cwd: string): Promise<ScriptOutcome>;

package/dist/skills.js

@@ -1,303 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveSkillRoots = resolveSkillRoots;
-exports.assertSafeSlug = assertSafeSlug;
-exports.resolveInstallDir = resolveInstallDir;
-exports.isUnownedInstallDir = isUnownedInstallDir;
-exports.materializeSkillFiles = materializeSkillFiles;
-exports.stageSkillFiles = stageSkillFiles;
-exports.linkSkill = linkSkill;
-exports.removeManagedSymlink = removeManagedSymlink;
-exports.runSkillScript = runSkillScript;
-const node_child_process_1 = require("node:child_process");
-const node_fs_1 = require("node:fs");
-const promises_1 = require("node:fs/promises");
-const node_os_1 = require("node:os");
-const node_path_1 = __importDefault(require("node:path"));
-const node_process_1 = __importDefault(require("node:process"));
-const node_util_1 = require("node:util");
-const tela_pantry_1 = require("@meistrari/tela-pantry");
-const run = (0, node_util_1.promisify)(node_child_process_1.execFile);
-/**
- * One real copy under `~/.agents/skills`, symlinked into `~/.claude/skills`.
- *
- * Agent tooling reads a fixed pair of locations, so there is nowhere else worth
- * installing to; the roots stay parameterised only so tests can work inside a
- * temporary home.
- */
-function resolveSkillRoots(home = (0, node_os_1.homedir)()) {
-    return {
-        installRoot: node_path_1.default.join(home, '.agents', 'skills'),
-        linkRoot: node_path_1.default.join(home, '.claude', 'skills'),
-    };
-}
-/**
- * A slug reaches `path.join` and, eventually, a recursive delete. `path.join`
- * collapses `..`, so validation has to happen before the join — and both
- * clauses are needed: `isSafeSkillPath` is an archive-path predicate that
- * accepts `a/b`, which as a slug is a traversal into a sibling directory.
- */
-function assertSafeSlug(slug, action) {
-    if (!(0, tela_pantry_1.isSafeSkillPath)(slug) || slug.includes('/'))
-        throw new Error(`Refusing to ${action}: "${slug}" is not a valid skill slug.`);
-}
-function resolveInstallDir(roots, slug) {
-    assertSafeSlug(slug, 'resolve');
-    return node_path_1.default.join(roots.installRoot, slug);
-}
-/**
- * The install guard: is something already sitting at the target that this CLI
- * did not put there?
- *
- * Compares the *recorded directory* rather than asking whether the slug is
- * registered at all. A registration pointing somewhere else is not permission
- * to replace what is at this path — which may be a directory the user created
- * by hand, or one another tool owns.
- */
-function isUnownedInstallDir(target, registeredDir) {
-    return (0, node_fs_1.existsSync)(target) && registeredDir !== target;
-}
-// Both the incoming extraction and the displaced previous install are parked
-// here. A slug can never contain `/`, so an install directory is always exactly
-// one component below the root — which means a scratch path two components
-// below it can never *be* some skill's install directory. The leading dot keeps
-// it out of the `*/SKILL.md` sweep an agent runs over the skills root, so
-// neither a half-written skill nor a displaced old one is ever advertised.
-const STAGING_DIR_NAME = '.tela-staging';
-function scratchDir(target, role) {
-    const unique = `${node_process_1.default.pid}.${Math.random().toString(36).slice(2, 10)}`;
-    return node_path_1.default.join(node_path_1.default.dirname(target), STAGING_DIR_NAME, `${node_path_1.default.basename(target)}.${unique}.${role}`);
-}
-/**
- * Write the verified files to `target`, replacing whatever is there.
- *
- * Nothing is deleted while the target is at risk. Everything is extracted to a
- * staging directory first, the previous install is renamed aside, the staged
- * copy is renamed in, and only then is the old copy dropped. Every destructive
- * step is a rename — which either happens or does not — and each has an
- * inverse, so an interrupted install can never leave a half-written skill where
- * a working one used to be.
- */
-async function materializeSkillFiles(target, files) {
-    const staged = await stageSkillFiles(target, files);
-    await staged.commit();
-}
-async function stageSkillFiles(target, files) {
-    const staging = scratchDir(target, 'staging');
-    const backup = scratchDir(target, 'backup');
-    let displaced = false;
-    try {
-        // Created up front rather than left to the write loop: the shared
-        // scratch parent has to exist before the target can be renamed into it.
-        // A manifest declaring no files would otherwise never create it, and
-        // the displacement below would fail with an ENOENT for its
-        // *destination* that reads exactly like "there was no previous install".
-        await (0, promises_1.mkdir)(staging, { recursive: true });
-        for (const file of files) {
-            const filePath = node_path_1.default.join(staging, file.path);
-            await (0, promises_1.mkdir)(node_path_1.default.dirname(filePath), { recursive: true });
-            await (0, promises_1.writeFile)(filePath, file.data);
-        }
-        displaced = await swapInStagedInstall(staging, target, backup);
-    }
-    catch (error) {
-        // Only the staging copy is dropped, and only after the swap has had its
-        // chance to put the previous install back: a backup still on disk here
-        // is one the rollback could not restore, and it is the user's only copy.
-        await (0, promises_1.rm)(staging, { recursive: true, force: true });
-        await removeScratchParent(staging);
-        throw error;
-    }
-    return {
-        commit: async () => {
-            if (displaced) {
-                // Best effort: the swap has landed, so what is on disk is
-                // already the correct install and a failure here costs a stray
-                // directory under the dotted scratch parent, nothing more.
-                await (0, promises_1.rm)(backup, { recursive: true, force: true }).catch(() => { });
-            }
-            await removeScratchParent(staging);
-        },
-        rollback: async () => {
-            try {
-                await restoreStagedInstall(target, backup, displaced);
-            }
-            finally {
-                await (0, promises_1.rm)(staging, { recursive: true, force: true }).catch(() => { });
-                await removeScratchParent(staging);
-            }
-        },
-    };
-}
-async function swapInStagedInstall(staging, target, backup) {
-    // `rename`, not `existsSync` then `rename`: whether something was there has
-    // to be answered by the operation that moves it, or the answer is a guess
-    // taken at a different instant.
-    let displaced = true;
-    try {
-        await (0, promises_1.rename)(target, backup);
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-        displaced = false;
-    }
-    try {
-        await (0, promises_1.rename)(staging, target);
-    }
-    catch (error) {
-        if (!displaced)
-            throw error;
-        try {
-            await (0, promises_1.rename)(backup, target);
-        }
-        catch (restoreError) {
-            throw new Error(`could not move the new install into place (${describeError(error)}), and the `
-                + `previous installation could not be moved back (${describeError(restoreError)}).\n`
-                + `There is now nothing at ${target}. The previous installation is intact at `
-                + `${backup} — move that directory back to ${target} by hand to recover it.`);
-        }
-        throw error;
-    }
-    return displaced;
-}
-async function restoreStagedInstall(target, backup, displaced) {
-    await (0, promises_1.rm)(target, { recursive: true, force: true });
-    if (!displaced)
-        return;
-    try {
-        await (0, promises_1.rename)(backup, target);
-    }
-    catch (error) {
-        throw new Error(`could not roll back ${target} to its previous installation (${describeError(error)}). `
-            + `The previous installation is intact at ${backup} — move that directory back by hand to recover it.`);
-    }
-}
-async function removeScratchParent(staging) {
-    // Non-recursive on purpose: `rmdir` only succeeds on an empty directory, so
-    // it tidies the shared scratch parent without any chance of taking a
-    // concurrent install's staging directory — or an unrestorable backup — with
-    // it.
-    await (0, promises_1.rmdir)(node_path_1.default.dirname(staging)).catch(() => { });
-}
-/**
- * Symlink the install directory into the link root.
- *
- * A real directory already at the link path is left alone unless `force` says
- * otherwise: it is something another tool or the user put there, and replacing
- * it silently would delete files this CLI never wrote. A symlink pointing
- * somewhere other than the install directory gets the same treatment.
- */
-async function linkSkill(roots, slug, target, force) {
-    const linkPath = node_path_1.default.join(roots.linkRoot, slug);
-    const replaceInstead = `Run \`tela skills install ${slug} --force\` to replace it, `
-        + 'or remove it by hand.';
-    try {
-        await (0, promises_1.mkdir)(roots.linkRoot, { recursive: true });
-    }
-    catch (error) {
-        return {
-            linked: [],
-            skipped: `${linkPath} could not be created (${describeError(error)}). ${replaceInstead}`,
-        };
-    }
-    const linkState = inspectLinkPath(linkPath);
-    if (linkState.kind === 'non-symlink' && !force)
-        return { linked: [], skipped: `${linkPath} exists and is not a symlink. ${replaceInstead}` };
-    if (linkState.kind === 'unreadable' && !force)
-        return { linked: [], skipped: `${linkPath} could not be inspected (${linkState.reason}). ${replaceInstead}` };
-    if (linkState.kind === 'symlink' && node_path_1.default.resolve(linkState.target) !== node_path_1.default.resolve(target) && !force) {
-        return {
-            linked: [],
-            skipped: `${linkPath} points at ${linkState.target}, not ${target}. ${replaceInstead}`,
-        };
-    }
-    try {
-        // Recursive only under `--force`. The check above is a separate syscall
-        // from this one, so a directory can appear at the path in between —
-        // and without force the only thing here that is ours to remove is a
-        // symlink. A non-recursive `rm` fails with EISDIR rather than deleting
-        // a tree nobody authorised replacing.
-        await (0, promises_1.rm)(linkPath, { recursive: force, force: true });
-        // Relative, so the pair survives the home directory being moved or
-        // mounted at a different path.
-        await (0, promises_1.symlink)(node_path_1.default.relative(roots.linkRoot, target), linkPath);
-    }
-    catch (error) {
-        return {
-            linked: [],
-            skipped: `${linkPath} could not be replaced (${describeError(error)}). ${replaceInstead}`,
-        };
-    }
-    return { linked: [linkPath], skipped: null };
-}
-function inspectLinkPath(linkPath) {
-    try {
-        if (!(0, node_fs_1.lstatSync)(linkPath).isSymbolicLink())
-            return { kind: 'non-symlink' };
-        return {
-            kind: 'symlink',
-            target: node_path_1.default.resolve(node_path_1.default.dirname(linkPath), (0, node_fs_1.readlinkSync)(linkPath)),
-        };
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return { kind: 'missing' };
-        return { kind: 'unreadable', reason: describeError(error) };
-    }
-}
-/**
- * Remove a symlink this CLI created that still points at the install directory.
- *
- * Every other case is reported and skipped. The link may since have been
- * replaced by a real directory belonging to something else, and uninstalling a
- * skill is not licence to delete it.
- */
-async function removeManagedSymlink(linkPath, target) {
-    try {
-        if (!(0, node_fs_1.lstatSync)(linkPath).isSymbolicLink())
-            return { removed: false, reason: `Skipped ${linkPath}: not a symlink` };
-        const resolved = node_path_1.default.resolve(node_path_1.default.dirname(linkPath), (0, node_fs_1.readlinkSync)(linkPath));
-        if (node_path_1.default.resolve(resolved) !== node_path_1.default.resolve(target))
-            return { removed: false, reason: `Skipped ${linkPath}: points at ${resolved}, not ${target}` };
-        // Non-recursive on purpose: if the entry is swapped for a real
-        // directory between the check above and this call, `rm` fails with
-        // EISDIR rather than deleting a tree.
-        await (0, promises_1.rm)(linkPath, { force: true });
-        return { removed: true, reason: null };
-    }
-    catch (error) {
-        // The link can change under us between any two of these calls. A throw
-        // here would abort an otherwise fine uninstall, leaving the skill both
-        // registered and on disk.
-        return { removed: false, reason: `Skipped ${linkPath}: ${describeError(error)}` };
-    }
-}
-/**
- * Run a skill's declared install or uninstall script, in the skill's own
- * directory.
- *
- * Both streams are captured and handed back rather than inherited: the script
- * is arbitrary shell from the catalog, and letting it write to stdout would
- * corrupt `--json` output. The caller relays them as diagnostics on stderr.
- */
-async function runSkillScript(script, cwd) {
-    try {
-        const { stdout, stderr } = await run('sh', ['-c', script], { cwd });
-        return { ok: true, output: [stdout, stderr].map(text => text.trimEnd()).filter(Boolean).join('\n') };
-    }
-    catch (error) {
-        const shell = error;
-        const output = [shell.stdout ?? '', shell.stderr ?? '', describeError(error)]
-            .map(text => text.trimEnd())
-            .filter(Boolean)
-            .join('\n');
-        return { ok: false, output };
-    }
-}
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}