talentos 0.2.0 → 1.0.0

package/dist/commands/login.js

@@ -0,0 +1,125 @@
+import { AgentClient, UNAUTHORIZED } from "../client.js";
+import { clearConfig, readConfig, resolveApiUrl, writeConfig, } from "../config.js";
+import { bold, emit } from "../format.js";
+import { checkPastedKey, defaultDeviceName, fetchLoginStatus, mintKey, openBrowser, startLogin, } from "../login.js";
+import { fetchWhoami, renderWhoami } from "./whoami.js";
+const POLL_INTERVAL_MS = 2000;
+/** A 5xx or a dropped wifi must not discard a key the member just approved. */
+const MAX_POLL_FAILURES = 5;
+const REJECTED_KEY = "TalentOS rejected that key. Create a new one in Settings → Agents & CLI, or run `talentos login` without --key.";
+export async function runLogin(parsed) {
+    const session = await authorize(parsed);
+    emit(`${bold("Logged in.")}\n${renderWhoami(session.who)}`);
+}
+/** The handshake: mint or accept a key, prove it works, then store it. */
+export async function authorize(parsed) {
+    const stored = await readConfig();
+    const apiUrl = resolveApiUrl(parsed.options["api-url"], stored.apiUrl);
+    const pasted = parsed.options.key;
+    const rawKey = pasted === undefined
+        ? await approveNewKey(apiUrl, parsed)
+        : checkPastedKey(pasted);
+    const who = await identify(apiUrl, rawKey).catch((error) => {
+        throw pasted === undefined ? asError(error) : rejected(error);
+    });
+    await writeConfig({ apiUrl, apiKey: rawKey });
+    return { credentials: { apiUrl, apiKey: rawKey }, who };
+}
+/** The stored key when it still works, so `init` can skip the handshake. */
+export async function currentSession(parsed) {
+    const stored = await readConfig();
+    const apiUrl = resolveApiUrl(parsed.options["api-url"], stored.apiUrl);
+    if (stored.apiKey === undefined) {
+        return;
+    }
+    try {
+        return {
+            credentials: { apiUrl, apiKey: stored.apiKey },
+            who: await identify(apiUrl, stored.apiKey),
+        };
+    }
+    catch {
+        return;
+    }
+}
+export async function runLogout() {
+    await clearConfig();
+    emit("Logged out. The key on the server is still valid until you revoke it.");
+}
+async function approveNewKey(apiUrl, parsed) {
+    const key = mintKey();
+    const deviceName = parsed.options.name ?? defaultDeviceName();
+    const start = await startLogin(apiUrl, {
+        hashedKey: key.hashedKey,
+        keyPrefix: key.keyPrefix,
+        deviceName,
+    });
+    emit(approvalNotice(start));
+    if (start.authorizeUrl) {
+        openBrowser(start.authorizeUrl);
+    }
+    const status = await pollUntilDecided(apiUrl, start, key.rawKey);
+    if (status !== "approved") {
+        throw new Error(`Login ${status}. Run \`talentos login\` to try again.`);
+    }
+    return key.rawKey;
+}
+/**
+ * Only the server knows which app url its keys belong to, so without a url
+ * from it the member navigates there themselves rather than to a guessed host.
+ */
+export function approvalNotice(start) {
+    const heading = `Approve this device in TalentOS:\n\n  ${bold(start.code)}\n`;
+    return start.authorizeUrl
+        ? `${heading}  ${start.authorizeUrl}\n`
+        : `${heading}\nOpen TalentOS in your browser, go to Settings → Agents & CLI, and enter this code.\n`;
+}
+/** Polls until the member decides, riding out transient failures. */
+export async function pollUntilDecided(apiUrl, start, rawKey, deps = { fetchStatus: fetchLoginStatus, wait: sleep }) {
+    let failures = 0;
+    while (Date.now() < start.expiresAt) {
+        await deps.wait(POLL_INTERVAL_MS);
+        try {
+            const status = await deps.fetchStatus(apiUrl, start.code, rawKey);
+            failures = 0;
+            if (status !== "pending") {
+                return status;
+            }
+        }
+        catch (error) {
+            failures += 1;
+            if (failures > MAX_POLL_FAILURES) {
+                throw new Error(lostContact(start.code, error));
+            }
+        }
+    }
+    return "expired";
+}
+/** Proves the key works before it is written to disk. */
+async function identify(apiUrl, apiKey) {
+    const client = new AgentClient({ apiUrl, apiKey });
+    try {
+        return await fetchWhoami(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+/** A key the member pasted is theirs to fix; the generic 401 hint misleads. */
+function rejected(error) {
+    return asError(error).message === UNAUTHORIZED
+        ? new Error(REJECTED_KEY)
+        : asError(error);
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function lostContact(code, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return `Lost contact with TalentOS while waiting for code ${code} (${reason}). If you approved it in the browser, run \`talentos login\` again and approve the new code.`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/commands/mcp.js

@@ -0,0 +1,48 @@
+import { AgentClient } from "../client.js";
+import { requireCredentials, resolveApiUrl } from "../config.js";
+import { dim, emit } from "../format.js";
+import { agentLabel, applyInstall, buildInstallSnippet, installHint, isAgentTarget, isMcpInstallTarget, MCP_INSTALL_TARGETS, } from "../install.js";
+export async function runMcp(parsed) {
+    if (parsed.action === "install") {
+        await runMcpInstall(parsed);
+        return;
+    }
+    if (parsed.action !== undefined) {
+        throw new Error(`Unknown command: mcp ${parsed.action}`);
+    }
+    const credentials = await requireCredentials();
+    const apiUrl = resolveApiUrl(parsed.options["api-url"], credentials.apiUrl);
+    // Loaded here so `mcp install` never pays for the server transport.
+    const { startMcpProxy } = await import("../mcp-proxy.js");
+    await startMcpProxy(new AgentClient({ ...credentials, apiUrl }));
+}
+async function runMcpInstall(parsed) {
+    const target = parsed.args[0];
+    if (target === undefined || !isMcpInstallTarget(target)) {
+        throw new Error(`Usage: talentos mcp install <${MCP_INSTALL_TARGETS.join("|")}> [--apply]`);
+    }
+    const stored = await requireCredentials();
+    const credentials = {
+        ...stored,
+        apiUrl: resolveApiUrl(parsed.options["api-url"], stored.apiUrl),
+    };
+    if (parsed.options.apply) {
+        await installFor(target, credentials);
+        return;
+    }
+    // Hint on stderr so `talentos mcp install cursor > mcp.json` writes only JSON.
+    process.stderr.write(`${dim(installHint(target))}\n\n`);
+    emit(buildInstallSnippet(target, credentials));
+}
+async function installFor(target, credentials) {
+    if (!isAgentTarget(target)) {
+        throw new Error("--apply needs a client to write to: claude, cursor or codex.");
+    }
+    const outcome = await applyInstall(target, credentials);
+    if (outcome.applied) {
+        emit(`Configured ${agentLabel(target)} — ${outcome.detail}`);
+        return;
+    }
+    process.stderr.write(`${dim(`${outcome.detail}. Run this yourself:`)}\n\n`);
+    emit(buildInstallSnippet(target, credentials));
+}

package/dist/commands/memory.js

@@ -0,0 +1,61 @@
+import { withClient } from "../client.js";
+import { emit, emitJson, formatDate, renderTable, truncate, } from "../format.js";
+const CONTENT_WIDTH = 80;
+export async function runMemory(parsed) {
+    switch (parsed.action) {
+        case "search":
+            return await searchMemory(parsed);
+        case "add":
+            return await addMemory(parsed);
+        default:
+            throw new Error('Usage: talentos memory <search "<query>"|add "<fact>"> — see `talentos memory --help`');
+    }
+}
+export function searchScopeFrom(options) {
+    if (options.personal) {
+        return "personal";
+    }
+    if (options.company) {
+        return "company";
+    }
+    return "all";
+}
+async function searchMemory(parsed) {
+    const query = parsed.args.join(" ").trim();
+    if (query === "") {
+        throw new Error('Usage: talentos memory search "<query>" [--personal|--company]');
+    }
+    const { data } = await withClient(parsed.options["api-url"], (client) => client.call("search_memory", {
+        query,
+        scope: searchScopeFrom(parsed.options),
+    }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    if (data.memories.length === 0) {
+        emit("Nothing remembered for that yet.");
+        return;
+    }
+    emit(renderTable(["SCOPE", "KIND", "UPDATED", "MEMORY"], data.memories.map((memory) => [
+        memory.scope,
+        memory.kind,
+        formatDate(memory.updatedAt),
+        truncate(memory.content, CONTENT_WIDTH),
+    ])));
+}
+async function addMemory(parsed) {
+    const content = parsed.args.join(" ").trim();
+    if (content === "") {
+        throw new Error('Usage: talentos memory add "<fact>" [--company]');
+    }
+    const { text, data } = await withClient(parsed.options["api-url"], (client) => client.call("remember", {
+        content,
+        scope: parsed.options.company ? "company" : "personal",
+    }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    emit(text);
+}

package/dist/commands/routines.js

@@ -0,0 +1,44 @@
+import { withClient } from "../client.js";
+import { emit, emitJson, emitLink, formatDate, renderTable, truncate, } from "../format.js";
+const NAME_WIDTH = 40;
+export async function runRoutines(parsed) {
+    switch (parsed.action) {
+        case "list":
+            return await listRoutines(parsed);
+        case "run":
+            return await runRoutine(parsed);
+        default:
+            throw new Error("Usage: talentos routines <list|run <id>>");
+    }
+}
+async function listRoutines(parsed) {
+    const { data } = await withClient(parsed.options["api-url"], (client) => client.call("list_routines", {}));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    if (data.routines.length === 0) {
+        emit("No routines yet.");
+        return;
+    }
+    emit(renderTable(["ID", "STATE", "SCHEDULE", "NEXT", "NAME"], data.routines.map((routine) => [
+        routine.id,
+        routine.state,
+        truncate(routine.schedule, 24),
+        formatDate(routine.nextRunAt ?? undefined),
+        truncate(routine.name, NAME_WIDTH),
+    ])));
+}
+async function runRoutine(parsed) {
+    const routineId = parsed.args[0];
+    if (routineId === undefined) {
+        throw new Error("Usage: talentos routines run <id>");
+    }
+    const { text, data } = await withClient(parsed.options["api-url"], (client) => client.call("run_routine", { routineId }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    emit(text);
+    emitLink(data.url);
+}

package/dist/commands/skills.js

@@ -0,0 +1,183 @@
+import { access } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { withClient } from "../client.js";
+import { bold, emit, emitJson, emitLink, formatDate, renderTable, truncate, warn, } from "../format.js";
+import { homeDir, pullDirs } from "../install.js";
+import { readSkillPackage, SKILL_ENTRY, writeSkillPackage, } from "../skill-files.js";
+const SUMMARY_WIDTH = 60;
+/** Enough to hide the round-trip latency of 100 skills without flooding. */
+const PULL_CONCURRENCY = 4;
+/** The server's ceiling: asking for less silently truncates at its default 50. */
+const PULL_LIMIT = 100;
+const ID_SUFFIX_LENGTH = 6;
+export async function runSkills(parsed) {
+    switch (parsed.action) {
+        case "list":
+            return await listSkills(parsed);
+        case "get":
+            return await getSkill(parsed);
+        case "push":
+            return await pushSkill(parsed);
+        case "pull":
+            return await pullSkills(parsed);
+        case "share":
+            return shareSkill();
+        default:
+            throw new Error("Usage: talentos skills <list|get|push|pull> — see `talentos skills --help`");
+    }
+}
+export function scopeFrom(options) {
+    if (options.mine) {
+        return "mine";
+    }
+    if (options.company) {
+        return "company";
+    }
+    return "all";
+}
+async function listSkills(parsed) {
+    const { data } = await withClient(parsed.options["api-url"], (client) => client.call("list_skills", {
+        scope: scopeFrom(parsed.options),
+        ...(parsed.options.query ? { query: parsed.options.query } : {}),
+    }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    if (data.skills.length === 0) {
+        emit("No skills yet. Push one with `talentos skills push <path>`.");
+        return;
+    }
+    emit(renderTable(["SLUG", "SCOPE", "V", "UPDATED", "NAME"], data.skills.map((skill) => [
+        skill.slug,
+        skill.scope,
+        `v${skill.version}`,
+        formatDate(skill.updatedAt),
+        truncate(skill.name, SUMMARY_WIDTH),
+    ])));
+}
+async function getSkill(parsed) {
+    const skillId = parsed.args[0];
+    if (skillId === undefined) {
+        throw new Error("Usage: talentos skills get <id|slug> [--out <dir>]");
+    }
+    const { text, data } = await withClient(parsed.options["api-url"], (client) => client.call("get_skill", { skillId }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    const out = parsed.options.out;
+    if (out === undefined) {
+        emit(text);
+        return;
+    }
+    const written = await writeSkillPackage(out, data.slug, data.files);
+    emit(`Wrote ${data.files.length} file(s) to ${written}`);
+    emitLink(data.url);
+}
+async function pushSkill(parsed) {
+    const path = parsed.args[0];
+    if (path === undefined) {
+        throw new Error("Usage: talentos skills push <SKILL.md|dir> [--id <skillId>]");
+    }
+    const files = await readSkillPackage(resolve(path));
+    const { data } = await withClient(parsed.options["api-url"], (client) => client.call("save_skill", {
+        files,
+        ...(parsed.options.id ? { skillId: parsed.options.id } : {}),
+    }));
+    if (parsed.options.json) {
+        emitJson(data);
+        return;
+    }
+    emit([
+        `${data.created ? "Created" : "Updated"} ${bold(data.slug)} v${data.version} (${data.id})`,
+        "Private to you. Open TalentOS to share it.",
+    ].join("\n"));
+    emitLink(data.url);
+}
+async function pullSkills(parsed) {
+    const dirs = pullDirs({
+        home: homeDir(),
+        target: parsed.options.for,
+        global: parsed.options.global,
+        to: parsed.options.to,
+    });
+    const results = await withClient(parsed.options["api-url"], (client) => pullInto(client, dirs, scopeFrom(parsed.options)));
+    if (parsed.options.json) {
+        emitJson(results);
+        return;
+    }
+    if (results.length === 0) {
+        emit("Nothing to pull.");
+        return;
+    }
+    const created = results.filter((result) => result.created).length;
+    emit([
+        renderTable(["SKILL", "STATUS"], results.map((result) => [
+            result.slug,
+            result.created ? "written" : "updated",
+        ])),
+        `${created} written, ${results.length - created} updated in ${dirs.map((dir) => resolve(dir)).join(", ")}`,
+    ].join("\n\n"));
+}
+function shareSkill() {
+    throw new Error("Share this Skill from TalentOS.");
+}
+/** Shared with `init`: every visible skill, written into each target folder. */
+export async function pullInto(client, dirs, scope) {
+    const { data } = await client.call("list_skills", { scope, limit: PULL_LIMIT });
+    if (data.skills.length === PULL_LIMIT) {
+        warn(`Pulled the first ${PULL_LIMIT} skills; there may be more. Narrow with --mine, --company or -q <query>.`);
+    }
+    const packages = await mapConcurrent(data.skills, PULL_CONCURRENCY, async (skill) => (await client.call("get_skill", { skillId: skill.id })).data);
+    const results = [];
+    const taken = new Set();
+    // Fetched in parallel, written in slug order, so a run is reproducible.
+    for (const pkg of [...packages].sort((a, b) => a.slug.localeCompare(b.slug))) {
+        const slug = folderFor(pkg, taken);
+        let created = false;
+        for (const dir of dirs) {
+            created = created || !(await exists(join(dir, slug, SKILL_ENTRY)));
+            await writeSkillPackage(dir, slug, pkg.files);
+        }
+        results.push({ slug, created });
+    }
+    return results;
+}
+/** Two skills may share a slug; the second keeps its own folder, not the first's. */
+function folderFor(pkg, taken) {
+    if (!taken.has(pkg.slug)) {
+        taken.add(pkg.slug);
+        return pkg.slug;
+    }
+    const unique = `${pkg.slug}-${pkg.id.slice(-ID_SUFFIX_LENGTH)}`;
+    warn(`Two skills share the slug ${pkg.slug}; wrote this one to ${unique}.`);
+    taken.add(unique);
+    return unique;
+}
+/** Runs `work` over `items` with at most `limit` in flight, keeping order. */
+async function mapConcurrent(items, limit, work) {
+    const results = [];
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            const item = items[index];
+            if (item !== undefined) {
+                results[index] = await work(item);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/whoami.js

@@ -0,0 +1,29 @@
+import { withClient } from "../client.js";
+import { bold, dim, emit, emitJson } from "../format.js";
+export async function fetchWhoami(client) {
+    const { data } = await client.call("whoami", {});
+    return data;
+}
+/** A member can exist before they have a name; the email always identifies them. */
+export function memberLabel(member) {
+    return member.name ?? member.email;
+}
+export function renderWhoami(who) {
+    const talent = who.talent
+        ? `${who.talent.name} (${who.talent.status})`
+        : "none yet";
+    return [
+        `${bold(memberLabel(who.member))}  ${dim(who.member.email)}`,
+        `${who.organization.name} · ${who.member.role}`,
+        `Talent: ${talent}`,
+        `Skills: ${who.counts.mySkills} mine, ${who.counts.companySkills} company · Routines: ${who.counts.routines}`,
+    ].join("\n");
+}
+export async function runWhoami(parsed) {
+    const who = await withClient(parsed.options["api-url"], fetchWhoami);
+    if (parsed.options.json) {
+        emitJson(who);
+        return;
+    }
+    emit(renderWhoami(who));
+}

package/dist/config.js

@@ -0,0 +1,70 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const TRAILING_SLASHES = /\/+$/;
+export const DEFAULT_API_URL = "https://woozy-oyster-769.convex.site";
+export function configDir(env = process.env) {
+    // An empty XDG_CONFIG_HOME is unset per the XDG spec; taking it literally
+    // would write the key into whatever directory the CLI was started from.
+    const base = env.XDG_CONFIG_HOME;
+    const root = base === undefined || base === "" ? join(homedir(), ".config") : base;
+    return join(root, "talentos");
+}
+export function configPath(env = process.env) {
+    return join(configDir(env), "config.json");
+}
+/**
+ * The API url from any source, normalised the same way: a pasted `--api-url`
+ * with a trailing slash must not produce `//mcp`.
+ */
+export function resolveApiUrl(override, fallback) {
+    const chosen = override === undefined || override.trim() === "" ? fallback : override;
+    return chosen.trim().replace(TRAILING_SLASHES, "");
+}
+/**
+ * File values first, then env overrides. A machine with TALENTOS_API_KEY set
+ * (CI, a container, `codex` launching the stdio proxy) must never fall back to
+ * whatever key happens to be on disk.
+ */
+export async function readConfig(env = process.env) {
+    const stored = await readStoredConfig(env);
+    const apiUrl = resolveApiUrl(env.TALENTOS_API_URL, stored.apiUrl ?? DEFAULT_API_URL);
+    const apiKey = env.TALENTOS_API_KEY ?? stored.apiKey;
+    return apiKey ? { apiUrl, apiKey } : { apiUrl };
+}
+export async function writeConfig(config, env = process.env) {
+    const dir = configDir(env);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = configPath(env);
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    return path;
+}
+export async function clearConfig(env = process.env) {
+    await rm(configPath(env), { force: true });
+}
+export async function requireCredentials(env = process.env) {
+    const config = await readConfig(env);
+    if (!config.apiKey) {
+        throw new Error("Not logged in. Run `talentos login`.");
+    }
+    return { apiUrl: config.apiUrl, apiKey: config.apiKey };
+}
+async function readStoredConfig(env) {
+    try {
+        const raw = await readFile(configPath(env), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object") {
+            return {};
+        }
+        const record = parsed;
+        return {
+            apiUrl: typeof record.apiUrl === "string" ? record.apiUrl : undefined,
+            apiKey: typeof record.apiKey === "string" ? record.apiKey : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/format.js

@@ -0,0 +1,54 @@
+const WHITESPACE = /\s+/g;
+const ANSI = {
+    bold: "",
+    dim: "",
+    reset: "",
+};
+function paint(code, text) {
+    return process.stdout.isTTY ? `${code}${text}${ANSI.reset}` : text;
+}
+export function bold(text) {
+    return paint(ANSI.bold, text);
+}
+export function dim(text) {
+    return paint(ANSI.dim, text);
+}
+/** Left-aligned columns padded to the widest cell; the last column is not padded. */
+export function renderTable(headers, rows) {
+    if (rows.length === 0) {
+        return "";
+    }
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? "").length)));
+    const line = (cells) => cells
+        .map((cell, index) => index === cells.length - 1 ? cell : cell.padEnd(widths[index] ?? 0))
+        .join("  ")
+        .trimEnd();
+    return [dim(line(headers)), ...rows.map(line)].join("\n");
+}
+export function emit(text) {
+    process.stdout.write(`${text}\n`);
+}
+/** The app deep link a tool result carries; absent when the backend has no app url. */
+export function emitLink(url) {
+    if (url) {
+        emit(dim(`Open: ${url}`));
+    }
+}
+/** Warnings go to stderr so `--json` on stdout stays machine-readable. */
+export function warn(text) {
+    process.stderr.write(`${dim(text)}\n`);
+}
+export function emitJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function truncate(text, max) {
+    const flat = text.replace(WHITESPACE, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}...`;
+}
+export function formatDate(value) {
+    if (value === undefined) {
+        return "";
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? "" : date.toISOString().slice(0, 10);
+}