dexto 1.14.4 → 2.0.0-beta.0

package/dist/cli/cloud/commands/secrets.js

@@ -0,0 +1,110 @@
+// `cloud secrets`: credentials the project's agents use without ever seeing them.
+import { unwrap } from '@dexto/cloud-client';
+import { argument, flag, listOption, PAGE_OPTIONS, pageQuery, readValue, requireConsent, stringOption, YES_OPTION, } from '../command.js';
+const COLUMNS = [
+    { header: 'id', value: (secret) => secret.id },
+    { header: 'name', value: (secret) => secret.name },
+    { header: 'hosts', value: (secret) => secret.hosts.join(',') },
+    { header: 'hint', value: (secret) => secret.hint },
+    { header: 'last used', value: (secret) => secret.last_used_at },
+];
+const PLACEMENT_OPTIONS = {
+    header: {
+        description: 'Send the value in this header instead of Authorization: Bearer.',
+        type: 'string',
+        valueName: 'NAME',
+    },
+    host: {
+        description: 'A public hostname the value may be sent to; repeat for more.',
+        multiple: true,
+        type: 'string',
+    },
+    prefix: { description: "Text before the value in --header, such as 'Token '.", type: 'string' },
+};
+const list = {
+    options: PAGE_OPTIONS,
+    path: ['cloud', 'secrets', 'list'],
+    summary: "List the project's secrets. Values are never shown.",
+    async run(context, input) {
+        const page = await unwrap(await (await context.client()).GET('/v1/secrets', { params: { query: pageQuery(input) } }));
+        context.output.list(page, COLUMNS);
+    },
+};
+const get = {
+    arguments: '<secret_id>',
+    path: ['cloud', 'secrets', 'get'],
+    summary: 'Show a secret, without its value.',
+    async run(context, input) {
+        context.output.record(await unwrap(await (await context.client()).GET('/v1/secrets/{secret_id}', {
+            params: { path: { secret_id: argument(input, 0, 'secret_id') } },
+        })));
+    },
+};
+const create = {
+    arguments: '<name>',
+    options: PLACEMENT_OPTIONS,
+    path: ['cloud', 'secrets', 'create'],
+    summary: 'Create a secret. Type the value when asked, or pipe it on stdin; it is never an argument.',
+    async run(context, input) {
+        const value = await readValue(context, 'Value: ', true);
+        const secret = await unwrap(await (await context.client()).POST('/v1/secrets', {
+            body: {
+                hosts: listOption(input, 'host'),
+                name: argument(input, 0, 'name'),
+                placement: placement(input) ?? { type: 'bearer' },
+                value,
+            },
+        }));
+        context.output.result(secret, `Created secret ${secret.id} (${secret.name}).`);
+    },
+};
+const update = {
+    arguments: '<secret_id>',
+    options: {
+        ...PLACEMENT_OPTIONS,
+        value: {
+            description: 'Replace the value: type it when asked, or pipe it.',
+            type: 'boolean',
+        },
+    },
+    path: ['cloud', 'secrets', 'update'],
+    summary: "Change a secret's hosts, placement or value.",
+    async run(context, input) {
+        const hosts = listOption(input, 'host');
+        const newPlacement = placement(input);
+        const value = flag(input, 'value')
+            ? await readValue(context, 'New value: ', true)
+            : undefined;
+        const secret = await unwrap(await (await context.client()).PATCH('/v1/secrets/{secret_id}', {
+            params: { path: { secret_id: argument(input, 0, 'secret_id') } },
+            body: {
+                ...(hosts.length === 0 ? {} : { hosts }),
+                ...(newPlacement === null ? {} : { placement: newPlacement }),
+                ...(value === undefined ? {} : { value }),
+            },
+        }));
+        context.output.result(secret, `Updated secret ${secret.id}.`);
+    },
+};
+const remove = {
+    arguments: '<secret_id>',
+    options: YES_OPTION,
+    path: ['cloud', 'secrets', 'delete'],
+    summary: 'Delete a secret. Refused while an active agent uses it.',
+    async run(context, input) {
+        const id = argument(input, 0, 'secret_id');
+        await requireConsent(context, flag(input, 'yes'), `Deleting secret ${id} can't be undone.`);
+        const result = await unwrap(await (await context.client()).DELETE('/v1/secrets/{secret_id}', {
+            params: { path: { secret_id: id } },
+        }));
+        context.output.result(result, `Deleted secret ${id}.`);
+    },
+};
+function placement(input) {
+    const header = stringOption(input, 'header');
+    if (header === undefined)
+        return null;
+    const prefix = stringOption(input, 'prefix');
+    return { name: header, type: 'header', ...(prefix === undefined ? {} : { prefix }) };
+}
+export const secretCommands = [list, get, create, update, remove];

package/dist/cli/cloud/commands/skills.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const skillCommands: readonly Command[];
+//# sourceMappingURL=skills.d.ts.map

package/dist/cli/cloud/commands/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/skills.ts"],"names":[],"mappings":"AAQA,OAAO,EAOH,KAAK,OAAO,EAEf,MAAM,eAAe,CAAC;AA0PvB,eAAO,MAAM,aAAa,EAAE,SAAS,OAAO,EAAW,CAAC"}

package/dist/cli/cloud/commands/skills.js

@@ -0,0 +1,202 @@
+// `skills push`: packs a local Skill folder and creates or updates it in the person's library.
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { argument, CommandFailure, flag, stringOption, UsageError, YES_OPTION, } from '../command.js';
+import { tarArchive } from '../tar.js';
+import { sendBytes } from '../transfer.js';
+import { formatBytes } from './files.js';
+import { agreeToCall, listWorkspaceTools, queryWorkspaceTool, toolCallLevel } from './workspace.js';
+/** The most files a Skill bundle takes. */
+const MAX_FILES = 200;
+const SLUG = /^[a-z0-9._-]{1,80}$/u;
+const PreparedSchema = z.object({
+    headers: z.record(z.string(), z.string()),
+    method: z.string(),
+    path: z.string(),
+    url: z.string(),
+});
+const SearchSchema = z.object({
+    skills: z.array(z.object({
+        slug: z.string(),
+        source: z.string(),
+        visibility: z.enum(['organization', 'private', 'shared']).nullable().default(null),
+    })),
+});
+const ImportedSchema = z.object({
+    location: z.object({ skillId: z.string() }),
+    slug: z.string(),
+    title: z.string(),
+});
+const push = {
+    arguments: '<folder>',
+    options: {
+        description: {
+            description: "What the Skill does (default: description in SKILL.md's header).",
+            type: 'string',
+        },
+        slug: {
+            description: "The Skill's slug (default: slug or name in SKILL.md's header, else the folder's name).",
+            type: 'string',
+        },
+        title: {
+            description: "The Skill's title (default: title in SKILL.md's header, else from the slug).",
+            type: 'string',
+        },
+        update: {
+            description: 'Update your Skill with this slug (default: update it if you have one, else create it).',
+            type: 'boolean',
+        },
+        ...YES_OPTION,
+    },
+    path: ['skills', 'push'],
+    summary: 'Pack a local Skill folder (SKILL.md at its root, dotfiles left out) and create or update it in your library.',
+    async run(context, input) {
+        const folder = argument(input, 0, 'folder');
+        const files = await readSkillFolder(folder);
+        const header = skillHeader(new globalThis.TextDecoder().decode(files[0]?.bytes));
+        const named = header.name !== undefined && SLUG.test(header.name) ? header.name : null;
+        const slug = stringOption(input, 'slug') ??
+            header.slug ??
+            named ??
+            path.basename(path.resolve(folder));
+        if (!SLUG.test(slug))
+            throw new UsageError(`${slug} can't be a Skill's slug: use up to 80 lowercase letters, digits, dots, dashes and underscores. Pass --slug.`);
+        const title = stringOption(input, 'title') ??
+            header.title ??
+            (named === null ? header.name : undefined) ??
+            titleFromSlug(slug);
+        const description = stringOption(input, 'description') ?? header.description;
+        if (description === undefined)
+            throw new UsageError("SKILL.md's header has no description. Add one there, or pass --description.");
+        const mode = flag(input, 'update') || (await ownsSkill(context, slug)) ? 'update' : 'create';
+        const metadata = { description, mode, slug, title };
+        // Ask before anything is sent: the import is what changes the library.
+        const tool = (await listWorkspaceTools(context)).find((each) => each.name === 'dexto_skill_bundle_import');
+        const agreed = tool === undefined
+            ? {}
+            : await agreeToCall(context, {
+                level: toolCallLevel(tool, metadata),
+                schema: tool.inputSchema,
+                title: `${mode === 'create' ? 'Create' : 'Update'} the Skill ${slug}`,
+            }, flag(input, 'yes'));
+        const archive = tarArchive(files);
+        const prepared = PreparedSchema.safeParse(await queryWorkspaceTool(context, 'dexto_upload_prepare', {
+            filename: `${slug}.tar`,
+            mimeType: 'application/x-tar',
+            purpose: 'skill-bundle',
+            sha256: createHash('sha256').update(archive).digest('hex'),
+            sizeBytes: archive.length,
+        }));
+        if (!prepared.success)
+            throw new CommandFailure('failed', "Dexto didn't say where to upload the bundle.", null);
+        const { headers, method, url } = prepared.data;
+        await sendBytes(context, { headers, method, url }, new globalThis.Blob([archive]));
+        const imported = await queryWorkspaceTool(context, 'dexto_skill_bundle_import', {
+            ...metadata,
+            uploadPath: prepared.data.path,
+            ...agreed,
+        });
+        const shown = ImportedSchema.safeParse(imported);
+        context.output.result(imported, shown.success
+            ? `${mode === 'create' ? 'Created' : 'Updated'} ${shown.data.title} (${shown.data.slug}, ${files.length} file${files.length === 1 ? '' : 's'}, ${formatBytes(archive.length)}): skill ${shown.data.location.skillId}.`
+            : JSON.stringify(imported, null, 2));
+    },
+};
+/**
+ * The folder's files, SKILL.md first, as the bundle takes them: relative paths, the executable bit
+ * kept. Names starting with a dot (`.git`, the reserved `.dexto`) and links are left out.
+ */
+async function readSkillFolder(folder) {
+    if ((await stat(folder).catch(() => null))?.isDirectory() !== true)
+        throw new UsageError(`${folder} is not a folder.`);
+    const found = [];
+    const visit = async (relative) => {
+        const entries = await readdir(path.join(folder, relative), { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const child = relative === '' ? entry.name : `${relative}/${entry.name}`;
+            if (entry.isDirectory())
+                await visit(child);
+            else if (entry.isFile())
+                found.push({
+                    executable: ((await stat(path.join(folder, child))).mode & 0o111) !== 0,
+                    path: child,
+                });
+        }
+    };
+    await visit('');
+    if (!found.some((file) => file.path === 'SKILL.md'))
+        throw new UsageError(`${folder} has no SKILL.md at its root.`);
+    if (found.length > MAX_FILES)
+        throw new UsageError(`${folder} has ${found.length} files; a Skill takes up to ${MAX_FILES}.`);
+    const ordered = [
+        ...found.filter((file) => file.path === 'SKILL.md'),
+        ...found.filter((file) => file.path !== 'SKILL.md'),
+    ];
+    return await Promise.all(ordered.map(async (file) => ({
+        ...file,
+        bytes: await readFile(path.join(folder, file.path)),
+    })));
+}
+/**
+ * Whether the person has a Skill with this slug they can save over: their own, or their
+ * organization's. One someone shared with them is theirs to copy, so a push makes the person's own.
+ */
+async function ownsSkill(context, slug) {
+    const found = SearchSchema.safeParse(await queryWorkspaceTool(context, 'dexto_skills_search', {
+        limit: 50,
+        query: slug,
+        source: 'library',
+    }));
+    return (found.success &&
+        found.data.skills.some((skill) => skill.slug === slug &&
+            skill.source === 'user' &&
+            (skill.visibility === 'private' || skill.visibility === 'organization')));
+}
+/**
+ * The plain fields of SKILL.md's `---` header: one-line values, quoted or not, and `>` or `|` blocks
+ * on the indented lines below.
+ */
+function skillHeader(text) {
+    const lines = text.split(/\r?\n/u);
+    if (lines[0] !== '---')
+        return {};
+    const end = lines.indexOf('---', 1);
+    const body = lines.slice(1, end === -1 ? 1 : end);
+    const fields = {};
+    for (const [index, line] of body.entries()) {
+        const match = /^(description|name|slug|title):\s*(.*)$/u.exec(line);
+        if (match === null)
+            continue;
+        const [, key = '', raw = ''] = match;
+        const value = /^[>|][-+]?$/u.test(raw)
+            ? blockValue(body.slice(index + 1), raw.startsWith('>') ? ' ' : '\n')
+            : unquote(raw.trim());
+        if (value.length > 0)
+            fields[key] = value;
+    }
+    return fields;
+}
+/** A `>` or `|` block: the indented lines after its key, joined. */
+function blockValue(lines, separator) {
+    const end = lines.findIndex((line) => line.length > 0 && !/^\s/u.test(line));
+    return (end === -1 ? lines : lines.slice(0, end))
+        .map((line) => line.trim())
+        .join(separator)
+        .trim();
+}
+function unquote(value) {
+    return /^(["']).*\1$/u.test(value) ? value.slice(1, -1) : value;
+}
+/** `llm-wiki` is `Llm Wiki`. */
+function titleFromSlug(slug) {
+    return slug
+        .split(/[-_.]+/u)
+        .filter((part) => part.length > 0)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join(' ');
+}
+export const skillCommands = [push];

package/dist/cli/cloud/commands/web.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const webCommands: readonly Command[];
+//# sourceMappingURL=web.d.ts.map

package/dist/cli/cloud/commands/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/web.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AA+D5D,eAAO,MAAM,WAAW,EAAE,SAAS,OAAO,EAAyB,CAAC"}

package/dist/cli/cloud/commands/web.js

@@ -0,0 +1,53 @@
+// `cloud search` and `cloud fetch`: the web as /v1/search and /v1/fetch serve it.
+import { unwrap } from '@dexto/cloud-client';
+import { integerOption } from '../command.js';
+const search = {
+    arguments: '<query...>',
+    options: {
+        num: { description: 'How many results (default 10).', type: 'string', valueName: 'N' },
+    },
+    path: ['cloud', 'search'],
+    summary: 'Search the web.',
+    async run(context, input) {
+        const numResults = integerOption(input, 'num');
+        const result = await unwrap(await (await context.client()).POST('/v1/search', {
+            body: {
+                query: input.positionals.join(' '),
+                ...(numResults === undefined ? {} : { num_results: numResults }),
+            },
+        }));
+        if (context.output.json)
+            return context.output.record(result);
+        for (const item of result.results)
+            context.runtime.writeOutput(`${item.title ?? item.url}\n  ${item.url}${item.highlights.length === 0 ? '' : `\n  ${item.highlights[0]}`}\n\n`);
+    },
+};
+const fetchPages = {
+    arguments: '<url...>',
+    options: {
+        'max-chars': {
+            description: 'Text characters per page, 100 to 100000 (default 20000).',
+            type: 'string',
+            valueName: 'N',
+        },
+    },
+    path: ['cloud', 'fetch'],
+    summary: 'Read up to 10 web pages as text.',
+    async run(context, input) {
+        const maxCharacters = integerOption(input, 'max-chars');
+        const result = await unwrap(await (await context.client()).POST('/v1/fetch', {
+            body: {
+                urls: [...input.positionals],
+                ...(maxCharacters === undefined ? {} : { max_characters: maxCharacters }),
+            },
+        }));
+        if (context.output.jsonContent)
+            return context.output.record(result);
+        for (const page of result.results)
+            context.runtime.writeOutput(page.status === 'ok'
+                ? `# ${page.title ?? page.url}\n${page.url}\n\n${page.text ?? ''}\n\n`
+                : `# ${page.url}\nFailed: ${page.error?.code ?? 'error'}\n\n`);
+        return result.results.some((page) => page.status === 'error') ? 1 : 0;
+    },
+};
+export const webCommands = [search, fetchPages];

package/dist/cli/cloud/commands/workspace-apps.d.ts

@@ -0,0 +1,58 @@
+import { type CommandContext } from '../command.js';
+import { type WorkspaceTool } from './workspace.js';
+/** One app or service: how many of its tools the sign-in reaches, and how many App actions it has. */
+export interface WorkspaceApp {
+    readonly actions: number;
+    readonly id: string;
+    readonly kind: string;
+    readonly tools: number;
+}
+/**
+ * One thing an app does: a workspace tool, one action of a tool that is the whole app (such as
+ * `dexto_drive`), or an App action run through `dexto_apps_action`.
+ */
+export interface Operation {
+    readonly call: {
+        readonly kind: 'action';
+        readonly toolName: string;
+    } | {
+        readonly action: string | null;
+        /** Each action's own level, where a tool's actions differ (`dexto/action_levels`). */
+        readonly actionLevels: Readonly<Record<string, string>>;
+        readonly kind: 'tool';
+        readonly name: string;
+    };
+    /** The schema whose `confirm` field says the person agreed: the tool's, or `dexto_apps_action`'s. */
+    readonly confirmSchema: unknown;
+    readonly description: string;
+    readonly inputSchema: unknown;
+    readonly level: string;
+    readonly name: string;
+    readonly title: string;
+}
+/**
+ * The apps the sign-in reaches: those whose manifests provide its tools, and the Apps whose
+ * actions it can run. Tools a server lists without a provider stay under `workspace call`.
+ */
+export declare function listWorkspaceApps(context: CommandContext): Promise<WorkspaceApp[]>;
+/** A command the CLI itself adds to an app, such as `drive put`, listed with the app's operations. */
+export interface AppCommand {
+    /** Its words after the app's, such as `put`. */
+    readonly name: string;
+    readonly summary: string;
+    readonly usage: string;
+}
+/** Runs `<app> [operation] [action] [--field value…]`; `commands` are the CLI's own for the app. */
+export declare function runWorkspaceApp(context: CommandContext, args: readonly string[], help: boolean, commands: readonly AppCommand[]): Promise<number>;
+/** A Dexto tool and the arguments to call it with, as search names a route's call. */
+export interface ToolCall {
+    readonly arguments: Readonly<Record<string, unknown>>;
+    readonly tool: string;
+}
+/**
+ * The CLI command that makes a call: `dexto workspace <app> <operation> --field value`, or
+ * `workspace call` when no app operation does. A value written `<type>` is left for the caller to
+ * fill in. `operationsByApp` keeps each app's operations across calls.
+ */
+export declare function commandForCall(context: CommandContext, tools: readonly WorkspaceTool[], call: ToolCall, operationsByApp: Map<string, Operation[]>): Promise<string>;
+//# sourceMappingURL=workspace-apps.d.ts.map

package/dist/cli/cloud/commands/workspace-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-apps.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/workspace-apps.ts"],"names":[],"mappings":"AAKA,OAAO,EAKH,KAAK,cAAc,EACtB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAMH,KAAK,aAAa,EACrB,MAAM,gBAAgB,CAAC;AAExB,sGAAsG;AACtG,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,IAAI,EACP;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACtD;QACI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,sFAAsF;QACtF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACzB,CAAC;IACR,qGAAqG;IACrG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAqBxF;AAED,sGAAsG;AACtG,MAAM,WAAW,UAAU;IACvB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,oGAAoG;AACpG,wBAAsB,eAAe,CACjC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,SAAS,UAAU,EAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAwDjB;AA0GD,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAChC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE,QAAQ,EACd,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,GAC1C,OAAO,CAAC,MAAM,CAAC,CA4CjB"}