talentos 0.3.0 → 1.0.0

package/dist/skill-files.js

@@ -0,0 +1,109 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
+export const SKILL_ENTRY = "SKILL.md";
+export const MAX_SKILL_FILES = 100;
+export const MAX_SKILL_BYTES = 512 * 1024;
+const PATH_SEPARATORS = /[/\\]/;
+const PARENT = "..";
+const SKIPPED_DIRS = new Set(["node_modules", ".git"]);
+/**
+ * Read a skill package from a SKILL.md path or the directory that contains one.
+ * Paths in the result are POSIX-relative to the package root, SKILL.md first,
+ * which is the order the backend hashes for idempotent `save_skill` retries.
+ */
+export async function readSkillPackage(entry) {
+    const info = await stat(entry).catch(() => null);
+    if (!info) {
+        throw new Error(`No such file or directory: ${entry}`);
+    }
+    if (info.isFile()) {
+        if (basename(entry) !== SKILL_ENTRY) {
+            throw new Error(`Expected ${SKILL_ENTRY} or a directory containing it: ${entry}`);
+        }
+        return [{ path: SKILL_ENTRY, text: await readFile(entry, "utf8") }];
+    }
+    const files = await readDirectoryFiles(entry);
+    if (!files.some((file) => file.path === SKILL_ENTRY)) {
+        throw new Error(`No ${SKILL_ENTRY} at the root of ${entry}`);
+    }
+    return sortSkillFiles(files);
+}
+/** Write a package to `<dir>/<slug>/...`; returns the package directory. */
+export async function writeSkillPackage(dir, slug, files) {
+    const root = resolve(dir, slug);
+    for (const file of files) {
+        if (escapesRoot(root, file.path)) {
+            throw new Error(`Refusing to write outside the skill folder: ${file.path}`);
+        }
+        const target = resolve(root, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, file.text, "utf8");
+    }
+    return root;
+}
+/**
+ * Server-sent paths are untrusted. `relative()` alone misses an absolute path
+ * and a Windows drive or UNC path, none of which need a `..` segment to land
+ * outside the folder — while a name like `..notes.md` is perfectly legitimate.
+ */
+function escapesRoot(root, path) {
+    if (isAbsolute(path) || win32.isAbsolute(path)) {
+        return true;
+    }
+    if (path.split(PATH_SEPARATORS).includes(PARENT)) {
+        return true;
+    }
+    const climb = relative(root, resolve(root, path));
+    return climb === PARENT || climb.startsWith(`${PARENT}${sep}`);
+}
+async function readDirectoryFiles(root) {
+    const files = [];
+    let bytes = 0;
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            break;
+        }
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const dirent of entries) {
+            const path = join(current, dirent.name);
+            if (dirent.isDirectory()) {
+                if (!SKIPPED_DIRS.has(dirent.name)) {
+                    queue.push(path);
+                }
+                continue;
+            }
+            if (!dirent.isFile()) {
+                continue;
+            }
+            const buffer = await readFile(path);
+            if (buffer.includes(0)) {
+                continue;
+            }
+            bytes += buffer.byteLength;
+            if (bytes > MAX_SKILL_BYTES) {
+                throw new Error(`Skill package is larger than ${MAX_SKILL_BYTES / 1024} KiB`);
+            }
+            files.push({
+                path: relative(root, path).split(sep).join("/"),
+                text: buffer.toString("utf8"),
+            });
+            if (files.length > MAX_SKILL_FILES) {
+                throw new Error(`Skill package has more than ${MAX_SKILL_FILES} files`);
+            }
+        }
+    }
+    return files;
+}
+function sortSkillFiles(files) {
+    return [...files].sort((a, b) => {
+        if (a.path === SKILL_ENTRY) {
+            return -1;
+        }
+        if (b.path === SKILL_ENTRY) {
+            return 1;
+        }
+        return a.path.localeCompare(b.path);
+    });
+}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "talentos",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "type": "module",
-  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and private Skill writes.",
+  "description": "TalentOS CLI: push and pull skills, read and write team memory, and delegate work to your Talent from any coding agent.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TalentOSOfficial/talentos-team.git",
+    "directory": "tools/talentos-cli"
+  },
   "bin": {
     "talentos": "./dist/index.js"
   },
@@ -10,12 +15,13 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "start": "tsx src/index.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "prepack": "rm -rf dist && tsc -p tsconfig.build.json"
   },
   "dependencies": {
@@ -25,6 +31,7 @@
   "devDependencies": {
     "@types/node": "^22",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
   }
 }

package/dist/api.js

@@ -1,210 +0,0 @@
-// The HTTP-client half of the MCP server: one function per TalentOS
-// /api/v0/* endpoint, returning MCP-shaped text results. Deliberately free of
-// MCP SDK imports (ToolResult is structurally CallToolResult-compatible) so
-// these handlers unit-test from the repo root against a mocked fetch without
-// installing this package's dependencies. Zero business logic lives here —
-// authz, org scoping, and visibility are all server-side.
-const WORKFLOWS_PATH = "/api/v0/workflows";
-const NODES_PATH = "/api/v0/nodes";
-const CONTEXT_PATH = "/api/v0/context";
-const SKILLS_PATH = "/api/v0/skills";
-// A hung deployment (connection accepted, no response) would otherwise leave the
-// tool call pending forever with no error; abort so it surfaces as networkError.
-const REQUEST_TIMEOUT_MS = 15_000;
-export async function listWorkflows(config) {
-    const result = await fetchJson(config, WORKFLOWS_PATH);
-    if ("error" in result) {
-        return result.error;
-    }
-    const workflows = result.body.workflows ?? [];
-    if (workflows.length === 0) {
-        return textResult("No workflows are visible to this API key.");
-    }
-    const lines = workflows.map((workflow) => {
-        const parts = [
-            `- ${workflow.title} (id: ${workflow.id})`,
-            `status: ${workflow.status}`,
-            `${workflow.stepCount} step(s)`,
-            `dept: ${workflow.department ?? "—"}`,
-            `updated ${workflow.updatedAt ?? "unknown"}`,
-        ];
-        if (workflow.description) {
-            parts.push(workflow.description);
-        }
-        return parts.join(" · ");
-    });
-    return textResult(`${workflows.length} workflow(s):\n${lines.join("\n")}`);
-}
-export async function getWorkflow(config, workflowId) {
-    const url = `${config.baseUrl}${WORKFLOWS_PATH}/${encodeURIComponent(workflowId)}`;
-    let response;
-    try {
-        response = await fetch(url, {
-            headers: {
-                Accept: "text/markdown",
-                Authorization: `Bearer ${config.apiKey}`,
-            },
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-    }
-    catch (error) {
-        return networkError(error);
-    }
-    if (!response.ok) {
-        return await httpError(response, workflowId);
-    }
-    // The wrong-URL failure mode is a login page or JSON error served from the
-    // wrong domain; a rewritten/stripped content-type on a real runbook is not.
-    // Reject only the clearly-wrong types so a text/plain runbook still passes.
-    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
-    if (contentType.includes("text/html") ||
-        contentType.includes("application/json")) {
-        return toolError(`Expected a Markdown runbook but got content-type "${contentType || "unknown"}". ${URL_HINT}`);
-    }
-    try {
-        return textResult(await response.text());
-    }
-    catch (error) {
-        return networkError(error);
-    }
-}
-export async function listNodes(config) {
-    const result = await fetchJson(config, NODES_PATH);
-    if ("error" in result) {
-        return result.error;
-    }
-    const nodes = result.body.nodes ?? [];
-    if (nodes.length === 0) {
-        return textResult("No company nodes are published.");
-    }
-    const lines = nodes.map((node) => {
-        const parts = [
-            `- ${node.name} (id: ${node.id})`,
-            node.stepType,
-            node.summary,
-        ];
-        if (Array.isArray(node.toolNames) && node.toolNames.length > 0) {
-            parts.push(`tools: ${node.toolNames.join(", ")}`);
-        }
-        return parts.join(" · ");
-    });
-    return textResult(`${nodes.length} node(s):\n${lines.join("\n")}`);
-}
-export async function getContext(config) {
-    const result = await fetchJson(config, CONTEXT_PATH);
-    if ("error" in result) {
-        return result.error;
-    }
-    // The org summary as-is: it is already a compact priming payload, and any
-    // formatting opinion belongs server-side, not in this wrapper.
-    return textResult(JSON.stringify(result.body, null, 2));
-}
-export async function createSkill(config, skill) {
-    return await writeSkill(config, SKILLS_PATH, skill, "Created");
-}
-export async function updateSkill(config, skillId, skill) {
-    return await writeSkill(config, `${SKILLS_PATH}/${encodeURIComponent(skillId)}`, skill, "Updated", skillId);
-}
-const URL_HINT = "The TALENTOS_API_URL may be wrong — it must point at the deployment's https://<name>.convex.site domain.";
-async function writeSkill(config, path, skill, action, skillId) {
-    const result = await fetchJson(config, path, path === SKILLS_PATH ? "POST" : "PUT", skill);
-    if ("error" in result) {
-        return result.error;
-    }
-    const id = result.body.skillId ?? skillId;
-    const version = result.body.version;
-    if (!id || version === undefined) {
-        return toolError(`The response was missing a skill id or version. ${URL_HINT}`);
-    }
-    return textResult(`${action} skill (id: ${id}) · version ${version}\nPrivate to this API key's owner; they curate it in their TalentOS Skills library.`);
-}
-function textResult(text) {
-    return { content: [{ text, type: "text" }] };
-}
-function toolError(text) {
-    return { content: [{ text, type: "text" }], isError: true };
-}
-async function httpError(response, workflowId) {
-    const { message } = await parseErrorBody(response);
-    if (response.status === 400 && message) {
-        return toolError(message);
-    }
-    if (response.status === 401) {
-        return toolError("Unauthorized (401). Check that TALENTOS_API_KEY is a valid, active key for this deployment.");
-    }
-    if (response.status === 404 && workflowId) {
-        return toolError(`No workflow with id "${workflowId}" exists, or it is not visible to this API key.`);
-    }
-    if (response.status === 409) {
-        return toolError(message ??
-            "This write conflicts with the current state. Reload and retry.");
-    }
-    if (response.status === 429) {
-        return toolError("Rate limited (429). This API key is over its requests-per-minute budget — wait a moment and retry.");
-    }
-    if (message) {
-        return toolError(`The TalentOS API returned ${response.status}: ${message}`);
-    }
-    return toolError(`The TalentOS API returned an unexpected status ${response.status}.`);
-}
-async function parseErrorBody(response) {
-    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
-    if (!contentType.includes("application/json")) {
-        return {};
-    }
-    try {
-        const body = await response.json();
-        if (typeof body === "object" &&
-            body !== null &&
-            typeof body.error === "string") {
-            return { message: body.error };
-        }
-    }
-    catch {
-        return {};
-    }
-    return {};
-}
-async function fetchJson(config, path, method = "GET", body, workflowId) {
-    let response;
-    try {
-        response = await fetch(`${config.baseUrl}${path}`, {
-            body: body === undefined ? undefined : JSON.stringify(body),
-            headers: {
-                Accept: "application/json",
-                Authorization: `Bearer ${config.apiKey}`,
-                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
-            },
-            method,
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-    }
-    catch (error) {
-        return { error: networkError(error) };
-    }
-    if (!response.ok) {
-        return { error: await httpError(response, workflowId) };
-    }
-    let parsed;
-    try {
-        parsed = await response.json();
-    }
-    catch {
-        return {
-            error: toolError(`The response was not valid JSON. ${URL_HINT}`),
-        };
-    }
-    if (parsed === null || typeof parsed !== "object") {
-        return {
-            error: toolError(`The response was not a JSON object. ${URL_HINT}`),
-        };
-    }
-    return { body: parsed };
-}
-function networkError(error) {
-    if (error instanceof Error && error.name === "TimeoutError") {
-        return toolError(`The TalentOS API did not respond within ${REQUEST_TIMEOUT_MS / 1000}s. The deployment may be overloaded or unreachable — check TALENTOS_API_URL and retry.`);
-    }
-    const detail = error instanceof Error ? error.message : String(error);
-    return toolError(`Could not reach the TalentOS API. Check TALENTOS_API_URL points at the deployment's .convex.site domain. (${detail})`);
-}