@meistrari/tela-cli 1.0.0 → 1.2.0

package/dist/skills.js

@@ -0,0 +1,303 @@
+"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);
+}

package/package.json

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

package/skills/tela-cli/SKILL.md

@@ -16,9 +16,9 @@ safe in non-interactive agent sessions.
 ## Core Rules
 
 - Use `tela agent ...` commands, not legacy top-level `sync`, `run`, `push`, or `feedback`.
-- Run `tela update` before relying on ingredient slugs; it refreshes the local Pantry cache under `TELA_HOME`.
-- Query Pantry before building a service integration from scratch: `tela api pantry GET /ingredients query==<term>`.
-- Read endpoint or library docs before calling a service: `tela docs endpoints <slug>` then `tela docs reference <slug> <METHOD> <PATH>`.
+- Run `tela service update` before relying on service slugs; it refreshes the local inventory under `TELA_HOME`.
+- Query Pantry before building a service integration from scratch: `tela service api pantry GET /ingredients query==<term>`.
+- Read endpoint or library docs before calling a service: `tela service docs endpoints <slug>` then `tela service docs reference <slug> <METHOD> <PATH>`.
 - Prefer `--json` for machine-readable output and errors.
 - Do not rely on prompts in coding-agent sessions; pass every required value by flag.
 - Do not print token material. Use `tela auth token --json` for metadata and `--raw` only when a shell command explicitly needs the token.
@@ -26,18 +26,26 @@ safe in non-interactive agent sessions.
 ## Pantry and Service Commands
 
 ```bash
-tela update --json
-tela api <slug> <METHOD> <PATH> [args...] --env <slug> --body <json> --pretty
-tela docs endpoints <slug> --pretty
-tela docs reference <slug> [METHOD PATH|file-path] --pretty
-tela docs guide <slug> [path]
-tela env list <ingredient-slug> --pretty
-tela env set <ingredient-slug> <environment>
+tela service update --json
+tela service list --json
+tela service show <slug> --json
+tela service api <slug> <METHOD> <PATH> [args...] --service-env <slug> --body <json> --pretty
+tela service docs endpoints <slug> --pretty
+tela service docs reference <slug> [METHOD PATH|file-path] --pretty
+tela service docs guide <slug> [path]
+tela service env list <slug> --pretty
+tela service env use <slug> <environment>
 ```
 
-HTTPie-style args for `tela api`:
+HTTPie-style args for `tela service api`:
 
 - `name=value` sends a JSON string field.
 - `name:=value` sends a raw JSON field.
 - `name==value` sends a query parameter.
 - `Header:value` sends a request header.
+
+## Authentication
+
+Use `tela auth login --no-interactive` in an agent session. Open the URL it
+prints, authorize the code, then run the exact `tela auth login --device-code`
+follow-up command. Use `tela auth whoami --json` to inspect the selected context.