@meistrari/tela-cli 1.1.0 → 1.2.0

package/dist/markdown.d.ts

@@ -0,0 +1,17 @@
+export type MarkdownTarget = {
+    isTTY?: boolean;
+    columns?: number;
+};
+/**
+ * Render markdown for a terminal, or hand it back untouched.
+ *
+ * Guides are markdown source, and markdown source is what a pipe or a file
+ * should receive — reflowed text and ANSI escapes would corrupt anything
+ * reading the output as data. Formatting is therefore reserved for an
+ * interactive terminal, where nobody is parsing it.
+ *
+ * `NO_COLOR` opts out too: it signals a reader that wants plain text, and
+ * partial rendering — restructured layout without the styling that made it
+ * legible — is worse than none.
+ */
+export declare function renderMarkdown(markdown: string, target?: MarkdownTarget, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/markdown.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMarkdown = renderMarkdown;
+const node_process_1 = __importDefault(require("node:process"));
+const DEFAULT_WIDTH = 80;
+const MAX_WIDTH = 100;
+/**
+ * Fence languages highlight.js has a working grammar for but does not register
+ * under the name people write. Registering them as real aliases means the fence
+ * keeps its own name and gets proper highlighting.
+ *
+ * Each of these was checked against the grammar rather than assumed:
+ *
+ * - `jsonc` — the `json` grammar already accepts line and block comments and
+ *   trailing commas, and marks them up correctly.
+ * - `mts`/`cts` — TypeScript's own module-file extensions.
+ * - `dotenv`/`env` — `ini` marks up `KEY=value`, `#` comments and quoted values.
+ *
+ * `json5` is deliberately absent: the `json` grammar rejects unquoted keys and
+ * single-quoted strings outright, so it would highlight nothing.
+ */
+const LANGUAGE_ALIASES = {
+    jsonc: 'json',
+    mts: 'typescript',
+    cts: 'typescript',
+    dotenv: 'ini',
+    env: 'ini',
+};
+/**
+ * Render markdown for a terminal, or hand it back untouched.
+ *
+ * Guides are markdown source, and markdown source is what a pipe or a file
+ * should receive — reflowed text and ANSI escapes would corrupt anything
+ * reading the output as data. Formatting is therefore reserved for an
+ * interactive terminal, where nobody is parsing it.
+ *
+ * `NO_COLOR` opts out too: it signals a reader that wants plain text, and
+ * partial rendering — restructured layout without the styling that made it
+ * legible — is worse than none.
+ */
+async function renderMarkdown(markdown, target = node_process_1.default.stdout, env = node_process_1.default.env) {
+    if (!target.isTTY || env.NO_COLOR)
+        return markdown;
+    try {
+        return await formatMarkdown(markdown, terminalWidth(target));
+    }
+    catch {
+        // A renderer failure must not cost the reader their document.
+        return markdown;
+    }
+}
+async function formatMarkdown(markdown, width) {
+    // Imported lazily: marked-terminal pulls in a syntax highlighter and costs
+    // ~54ms to load, which every other `tela` command would otherwise pay for
+    // a renderer it never uses.
+    const { Marked } = await import('marked');
+    // @ts-expect-error marked-terminal ships no declarations, and
+    // @types/marked-terminal is still on v6 while the runtime here is v7;
+    // MarkedTerminal above describes the one export used.
+    const { markedTerminal } = await import('marked-terminal');
+    const { supportsLanguage } = await import('cli-highlight');
+    await registerLanguageAliases();
+    // A fresh instance rather than the `marked` singleton: `marked.use()` is
+    // global, and this must not change how anything else parses markdown.
+    const renderer = new Marked();
+    renderer.use(markedTerminal({ width, reflowText: true, tab: 2 }));
+    renderer.use({
+        /**
+         * Anything still unrecognised — `mermaid`, `hcl`, whatever a README
+         * invents — renders as plain code. highlight.js would otherwise print
+         * "Could not find the language 'x'" to stderr and carry on, turning an
+         * ordinary fence into what reads like a CLI error.
+         */
+        walkTokens(token) {
+            if (token.type !== 'code')
+                return;
+            // marked types `lang` loosely across the token union.
+            const fence = token;
+            const declared = typeof fence.lang === 'string' ? fence.lang : '';
+            const language = declared.trim().split(/\s+/)[0] ?? '';
+            if (language && !supportsLanguage(language))
+                fence.lang = '';
+        },
+    });
+    const rendered = renderer.parse(markdown);
+    if (typeof rendered !== 'string')
+        throw new TypeError('marked returned a promise');
+    return rendered;
+}
+let aliasesRegistered = false;
+/**
+ * Teach highlight.js the alias names, once per process.
+ *
+ * `cli-highlight` resolves the same `highlight.js` singleton this imports, so
+ * registering here is what makes `supportsLanguage('jsonc')` true and gets the
+ * fence highlighted under its own name.
+ */
+async function registerLanguageAliases() {
+    if (aliasesRegistered)
+        return;
+    aliasesRegistered = true;
+    const hljs = (await import('highlight.js')).default;
+    for (const [alias, language] of Object.entries(LANGUAGE_ALIASES)) {
+        if (!hljs.getLanguage(alias) && hljs.getLanguage(language))
+            hljs.registerAliases([alias], { languageName: language });
+    }
+}
+function terminalWidth(target) {
+    const columns = target.columns ?? DEFAULT_WIDTH;
+    // Long measures are hard to read, and a very narrow terminal reflows to
+    // nothing useful.
+    return Math.max(40, Math.min(columns, MAX_WIDTH));
+}

package/dist/program.js

@@ -3,14 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const tela_agent_1 = require("@meistrari/tela-agent");
-const cli_1 = require("@meistrari/workflow-code/cli");
 const output_1 = require("./output");
 const auth_1 = require("./commands/auth");
 const context_1 = require("./commands/context");
 const doctor_auth_1 = require("./commands/doctor-auth");
 const env_1 = require("./commands/env");
 const ingredients_1 = require("./commands/ingredients");
+const skills_1 = require("./commands/skills");
 async function runCli(argv, io) {
     const { args, options } = parseGlobalOptions(argv);
     const [command, ...rest] = args;
@@ -30,10 +29,18 @@ async function runCli(argv, io) {
         return await (0, env_1.runEnvCommand)(rest, options, io);
     if (command === 'doctor')
         return await (0, doctor_auth_1.runDoctorCommand)(rest, options, io);
-    if (command === 'agent')
-        return await (0, tela_agent_1.runAgentCli)(rest, io, options);
-    if (command === 'workflow')
-        return await (0, cli_1.runWorkflowCli)(rest, io, options);
+    if (command === 'service')
+        return await (0, ingredients_1.runServiceCommand)(rest, options, io);
+    if (command === 'skills' || command === 'skill')
+        return await (0, skills_1.runSkillsCommand)(rest, options, io);
+    if (command === 'agent') {
+        const { runAgentCli } = await import('@meistrari/tela-agent');
+        return await runAgentCli(rest, io, options);
+    }
+    if (command === 'workflow') {
+        const { runWorkflowCli } = await import('@meistrari/workflow-code/cli');
+        return await runWorkflowCli(rest, io, options);
+    }
     if (command === 'update' || command === 'api' || command === 'docs' || command === 'whoami' || command === 'token') {
         return await (0, ingredients_1.runTelactlCommand)(command, rest, options, io);
     }
@@ -60,7 +67,7 @@ function writeHelp(io) {
     (0, output_1.writeLine)(io, 'Usage: tela <command> [args]');
     (0, output_1.writeLine)(io);
     (0, output_1.writeLine)(io, 'Commands:');
-    (0, output_1.writeLine)(io, '  auth token [--context <context-id>] [--kind access-token|data-token] [--raw] [--json]');
+    (0, output_1.writeLine)(io, '  auth login|logout|whoami|token [options]');
     (0, output_1.writeLine)(io, '  context current [--json]');
     (0, output_1.writeLine)(io, '  context list [--json]');
     (0, output_1.writeLine)(io, '  context show <context-id> [--json]');
@@ -69,13 +76,14 @@ function writeHelp(io) {
     (0, output_1.writeLine)(io, '  env list <ingredient-slug> [-p|--pretty|--json]');
     (0, output_1.writeLine)(io, '  env set <ingredient-slug> <environment>');
     (0, output_1.writeLine)(io, '  doctor auth [--json]');
-    (0, output_1.writeLine)(io, '  update [--context <context-id>] [--json]');
-    (0, output_1.writeLine)(io, '  api <slug> <METHOD> <PATH> [args...] [--env <slug>] [--body <json>] [-p|--pretty]');
-    (0, output_1.writeLine)(io, '  docs endpoints <slug> [-p|--pretty] [--json]');
-    (0, output_1.writeLine)(io, '  docs reference <slug> [METHOD PATH|file-path] [-p|--pretty] [--json]');
-    (0, output_1.writeLine)(io, '  docs guide <slug> [path] [-p|--pretty]');
-    (0, output_1.writeLine)(io, '  whoami [--context <context-id>] [-p|--pretty]');
-    (0, output_1.writeLine)(io, '  token [--context <context-id>]');
+    (0, output_1.writeLine)(io, '  service list|show|api|docs|env [options]');
+    (0, output_1.writeLine)(io, '  service api <slug> <METHOD> <PATH> [args...] [--service-env <slug>] [-p|--pretty]');
+    (0, output_1.writeLine)(io, '  service docs reference <slug> [METHOD PATH|file-path] [-p|--pretty] [--json]');
+    (0, output_1.writeLine)(io, '  skills list|search|files|cat [options]');
+    (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]');
+    (0, output_1.writeLine)(io, '  api|docs|whoami|token ...       Legacy compatibility aliases');
     (0, output_1.writeLine)(io, '  version');
     (0, output_1.writeLine)(io, '  workflow init [--directory <path>] [--config <path>] [--workflow <key>...] [--yes] [--json]');
     (0, output_1.writeLine)(io, '  workflow compile [target] [--config <path>] [--env <path>] [--json]');

package/dist/session.d.ts

@@ -0,0 +1,28 @@
+import type { CredentialRef, ResolvedContext, StoredCredential, TelaLocalConfig } from '@meistrari/tela-local-config';
+import type { PantryClient } from '@meistrari/tela-pantry';
+export type Session = {
+    resolved: ResolvedContext;
+    credentialRef: CredentialRef;
+    credential: StoredCredential;
+    refreshed: boolean;
+};
+/** What opening a Pantry client needs in order to pick a context. */
+export type CatalogFlags = {
+    contextId?: string;
+    environmentId?: string;
+};
+export type PantrySession = {
+    client: PantryClient;
+    baseUrl: string;
+};
+/**
+ * Open an authenticated Pantry client for the selected context.
+ *
+ * There is no local catalog: Pantry runs in one environment and answers in
+ * ~200ms, so every command reads it live rather than keeping a copy that has to
+ * be invalidated.
+ */
+export declare function loadPantry(flags: CatalogFlags): Promise<PantrySession>;
+export declare function loadPantryForContext(resolved: ResolvedContext, config?: TelaLocalConfig): Promise<PantrySession>;
+export declare function loadSession(contextId?: string, environmentId?: string): Promise<Session>;
+export declare function resolvePantryBaseUrl(resolved: ResolvedContext): string;

package/dist/session.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPantry = loadPantry;
+exports.loadPantryForContext = loadPantryForContext;
+exports.loadSession = loadSession;
+exports.resolvePantryBaseUrl = resolvePantryBaseUrl;
+const tela_local_config_1 = require("@meistrari/tela-local-config");
+const tela_pantry_1 = require("@meistrari/tela-pantry");
+const credentials_1 = require("./credentials");
+const ENV_ACCESS_TOKEN_REF = {
+    provider: 'env',
+    service: 'env',
+    account: 'TELA_ACCESS_TOKEN',
+    kind: 'user-session',
+};
+/**
+ * Open an authenticated Pantry client for the selected context.
+ *
+ * There is no local catalog: Pantry runs in one environment and answers in
+ * ~200ms, so every command reads it live rather than keeping a copy that has to
+ * be invalidated.
+ */
+async function loadPantry(flags) {
+    const config = await (0, tela_local_config_1.loadConfig)();
+    const resolved = (0, tela_local_config_1.resolveContext)(config, {
+        contextId: flags.contextId,
+        environmentId: flags.environmentId,
+    });
+    return await loadPantryForContext(resolved, config);
+}
+async function loadPantryForContext(resolved, config) {
+    const loadedConfig = config ?? await (0, tela_local_config_1.loadConfig)();
+    const baseUrl = resolvePantryBaseUrl(resolved);
+    const credential = await loadPantryCredential(loadedConfig, resolved);
+    return { client: (0, tela_pantry_1.createPantryClient)(baseUrl, credential), baseUrl };
+}
+async function loadPantryCredential(config, selected) {
+    const credentials = (0, credentials_1.createCliCredentialAdapter)();
+    const candidates = pantryCredentialCandidates(config, selected);
+    for (const candidate of candidates) {
+        const originalCredential = await credentials.get(candidate.credentialRef);
+        if (!originalCredential)
+            continue;
+        const credential = originalCredential.kind === 'user-session'
+            ? await (0, tela_local_config_1.refreshUserSessionCredential)(candidate.resolved.environment, candidate.credentialRef, originalCredential, credentials)
+            : originalCredential;
+        if (credential.accessToken)
+            return credential;
+    }
+    throw new Error(`Pantry discovery requires a user-session access token for Tela environment '${selected.context.environmentId}'. `
+        + 'Run `tela auth login` or set TELA_ACCESS_TOKEN.');
+}
+function pantryCredentialCandidates(config, selected) {
+    const candidates = [];
+    const seen = new Set();
+    const addContext = (contextId) => {
+        if (!contextId || seen.has(contextId))
+            return;
+        const context = config.contexts[contextId];
+        if (!context || context.environmentId !== selected.context.environmentId)
+            return;
+        if (context.credentialRef.kind !== 'user-session')
+            return;
+        const environment = config.environments[context.environmentId];
+        if (!environment)
+            return;
+        seen.add(contextId);
+        candidates.push({
+            resolved: {
+                id: contextId,
+                context,
+                environment,
+            },
+            credentialRef: context.credentialRef,
+        });
+    };
+    if (selected.context.credentialRef.kind === 'user-session')
+        addContext(selected.id);
+    addContext(config.activeContextId);
+    for (const contextId of Object.keys(config.contexts))
+        addContext(contextId);
+    candidates.push({ resolved: selected, credentialRef: ENV_ACCESS_TOKEN_REF });
+    return candidates;
+}
+async function loadSession(contextId, environmentId) {
+    const config = await (0, tela_local_config_1.loadConfig)();
+    const resolved = (0, tela_local_config_1.resolveContext)(config, { contextId, environmentId });
+    const credentials = (0, credentials_1.createCliCredentialAdapter)();
+    const credentialRef = resolved.context.credentialRef;
+    const originalCredential = await credentials.get(credentialRef);
+    if (!originalCredential)
+        throw new Error(`Missing credential for Tela context ${resolved.id}`);
+    const credential = originalCredential.kind === 'user-session'
+        ? await (0, tela_local_config_1.refreshUserSessionCredential)(resolved.environment, credentialRef, originalCredential, credentials)
+        : originalCredential;
+    return {
+        resolved,
+        credentialRef,
+        credential,
+        refreshed: credential !== originalCredential,
+    };
+}
+function resolvePantryBaseUrl(resolved) {
+    const baseUrl = resolved.environment.services.pantry;
+    if (baseUrl)
+        return baseUrl;
+    throw new Error(`Tela environment '${resolved.context.environmentId}' does not configure a Pantry service URL. `
+        + 'Select a context whose environment defines services.pantry.');
+}

package/dist/skills.d.ts

@@ -0,0 +1,87 @@
+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>;