@molecule/app-ide-react 1.0.0

package/dist/components/chat-settings-utilities.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure helpers backing the `/settings` view.
+ *
+ * The list of user-controllable settings itself now lives in the React-free
+ * {@link module:../settings-metadata | settings-metadata} module at the package
+ * root — the **single source of truth** that can be imported on either side of
+ * the api/app boundary (the IDE `/settings` card here, and the molecule.dev API
+ * system prompt's "User-Controllable Settings" section via the package's
+ * `./settings-metadata` subpath export). This module adds no settings of its
+ * own; it zips that canonical metadata together with the already-formatted,
+ * display-ready current values into a flat list of {@link SettingDescriptor}s
+ * the React {@link SettingsCard} renders. Splitting the value-binding out of the
+ * component lets it be unit tested without rendering, and deriving from the
+ * shared metadata is what keeps the settings card and the canonical list (and
+ * the command menu) from ever drifting apart — the SYN11 fix.
+ *
+ * All prose in the metadata is the English default; the {@link SettingsCard}
+ * wraps each `label`/`description` in `t('ide.chat.settings.<id>.…', …,
+ * { defaultValue })` at render time. The `value` is the already-formatted,
+ * display-ready current value supplied by the caller (so dynamic,
+ * possibly-localized fragments stay out of this pure layer).
+ *
+ * @module
+ */
+import type { SettingKey, SettingMeta } from '../settings-metadata.js';
+/** Notification-sound mode for a single event (mirrors ChatPanel's `SoundMode`). */
+export type SoundEventMode = 'off' | 'whenNotFocused' | 'always';
+/**
+ * A canonical {@link SettingMeta} paired with its display-ready current value —
+ * what the `/settings` card renders for one row.
+ */
+export type SettingDescriptor = SettingMeta & {
+    /** The formatted, display-ready current value (already localized by caller). */
+    value: string;
+};
+/**
+ * Display-ready current values for the user-controllable settings, keyed by the
+ * canonical {@link SettingKey}. The caller resolves these (model labels from the
+ * catalog, on/off and mode words via `t()`, the effort label, the sounds summary
+ * via {@link summarizeSounds}) so this layer stays pure.
+ */
+export type SettingsDisplayValues = Record<SettingKey, string>;
+/**
+ * Builds the ordered list of user-controllable agent settings by zipping the
+ * canonical {@link SETTINGS} metadata together with the supplied display-ready
+ * values, so the `/settings` card always shows the live state AND can never
+ * drift from the shared single source of truth.
+ *
+ * Each `description` may contain the `{{agentName}}` interpolation token; the
+ * caller ({@link SettingsCard}) fills it in from the host's agent identity
+ * (neutral default: "the assistant") at render time.
+ *
+ * @param values - Display-ready current values for each setting, keyed by {@link SettingKey}.
+ * @returns One {@link SettingDescriptor} per setting in {@link SETTINGS}, in display order.
+ */
+export declare function buildSettingsList(values: SettingsDisplayValues): SettingDescriptor[];
+/** Aggregate enabled/total counts for a notification-sounds config. */
+export interface SoundsSummary {
+    /** Number of events set to anything other than `'off'`. */
+    enabled: number;
+    /** Total number of sound events. */
+    total: number;
+}
+/**
+ * Summarizes a notification-sounds config into enabled/total counts. Pure and
+ * deterministic; the component turns the counts into a localized string.
+ *
+ * @param sounds - Per-event sound modes (event name → mode).
+ * @returns The number of enabled events and the total event count.
+ */
+export declare function summarizeSounds(sounds: Record<string, SoundEventMode>): SoundsSummary;
+//# sourceMappingURL=chat-settings-utilities.d.ts.map

package/dist/components/chat-settings-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-settings-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-settings-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAGtE,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,gBAAgB,GAAG,QAAQ,CAAA;AAEhE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,qBAAqB,GAAG,iBAAiB,EAAE,CAEpF;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,aAAa,CAMrF"}

package/dist/components/chat-settings-utilities.js

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers backing the `/settings` view.
+ *
+ * The list of user-controllable settings itself now lives in the React-free
+ * {@link module:../settings-metadata | settings-metadata} module at the package
+ * root — the **single source of truth** that can be imported on either side of
+ * the api/app boundary (the IDE `/settings` card here, and the molecule.dev API
+ * system prompt's "User-Controllable Settings" section via the package's
+ * `./settings-metadata` subpath export). This module adds no settings of its
+ * own; it zips that canonical metadata together with the already-formatted,
+ * display-ready current values into a flat list of {@link SettingDescriptor}s
+ * the React {@link SettingsCard} renders. Splitting the value-binding out of the
+ * component lets it be unit tested without rendering, and deriving from the
+ * shared metadata is what keeps the settings card and the canonical list (and
+ * the command menu) from ever drifting apart — the SYN11 fix.
+ *
+ * All prose in the metadata is the English default; the {@link SettingsCard}
+ * wraps each `label`/`description` in `t('ide.chat.settings.<id>.…', …,
+ * { defaultValue })` at render time. The `value` is the already-formatted,
+ * display-ready current value supplied by the caller (so dynamic,
+ * possibly-localized fragments stay out of this pure layer).
+ *
+ * @module
+ */
+import { SETTINGS } from '../settings-metadata.js';
+/**
+ * Builds the ordered list of user-controllable agent settings by zipping the
+ * canonical {@link SETTINGS} metadata together with the supplied display-ready
+ * values, so the `/settings` card always shows the live state AND can never
+ * drift from the shared single source of truth.
+ *
+ * Each `description` may contain the `{{agentName}}` interpolation token; the
+ * caller ({@link SettingsCard}) fills it in from the host's agent identity
+ * (neutral default: "the assistant") at render time.
+ *
+ * @param values - Display-ready current values for each setting, keyed by {@link SettingKey}.
+ * @returns One {@link SettingDescriptor} per setting in {@link SETTINGS}, in display order.
+ */
+export function buildSettingsList(values) {
+    return SETTINGS.map((meta) => ({ ...meta, value: values[meta.id] }));
+}
+/**
+ * Summarizes a notification-sounds config into enabled/total counts. Pure and
+ * deterministic; the component turns the counts into a localized string.
+ *
+ * @param sounds - Per-event sound modes (event name → mode).
+ * @returns The number of enabled events and the total event count.
+ */
+export function summarizeSounds(sounds) {
+    const modes = Object.values(sounds);
+    return {
+        enabled: modes.filter((mode) => mode !== 'off').length,
+        total: modes.length,
+    };
+}
+//# sourceMappingURL=chat-settings-utilities.js.map

package/dist/components/chat-settings-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-settings-utilities.js","sourceRoot":"","sources":["../../src/components/chat-settings-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAsBlD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA6B;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;AACtE,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAsC;IACpE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACnC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,MAAM;QACtD,KAAK,EAAE,KAAK,CAAC,MAAM;KACpB,CAAA;AACH,CAAC"}

package/dist/components/chat-share-utilities.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure helpers backing the `/share <role>` command and the header share button.
+ *
+ * `/share` creates a public share link for the current project by POSTing
+ * `{ role }` to `POST /projects/:projectId/shares`. The backend (wired in the
+ * host app) mints a slug-bearing link row and returns it; anyone who opens
+ * `GET /share/:slug` is granted that role — a `viewer` link is an
+ * unauthenticated read. Roles, least- to most-privileged: viewer, commenter,
+ * editor, owner. The default — and the safest — role is `viewer`.
+ *
+ * These helpers parse the command, validate the role against the shared
+ * contract, build the exact POST body, and resolve the copyable public URL from
+ * the response. They are deterministic and side-effect free so they can be unit
+ * tested without rendering or a backend. The role labels are English defaults
+ * the component wraps in `t()` at render.
+ *
+ * @module
+ */
+/**
+ * Share roles, ordered least- to most-privileged. Mirrors the
+ * `@molecule/api-resource-share` `SHARE_ROLES` contract; duplicated here (rather
+ * than imported) because an `app-*` package may not import an `api-*` package
+ * across the stack boundary.
+ */
+export declare const SHARE_ROLES: readonly ["viewer", "commenter", "editor", "owner"];
+/** A role granted by a share link. */
+export type ShareRole = (typeof SHARE_ROLES)[number];
+/** The default (and safest) role when `/share` is run with no argument. */
+export declare const DEFAULT_SHARE_ROLE: ShareRole;
+/** Short English labels per role (the component wraps these in `t()` at render). */
+export declare const SHARE_ROLE_LABELS: Record<ShareRole, string>;
+/** The `POST /projects/:projectId/shares` request body. */
+export interface SharePayload {
+    /** Role granted to anyone who opens the link. */
+    role: ShareRole;
+}
+/**
+ * The `POST /projects/:projectId/shares` response — the created public link.
+ * Mirrors the relevant fields of the `@molecule/api-resource-share` `ShareLink`.
+ */
+export interface ShareLinkResult {
+    /** The link's unique id (used by the revoke route). */
+    id?: string;
+    /** Opaque slug embedded in the public URL. */
+    slug: string;
+    /** The role this link grants. */
+    role: ShareRole;
+    /**
+     * A fully-qualified share URL, when the backend supplies one. Preferred over
+     * client-side construction so the canonical origin (e.g. a custom domain)
+     * wins over the current page origin.
+     */
+    url?: string;
+}
+/**
+ * The parsed result of a `/share` command:
+ *
+ * - `create` — POST a link at a valid role (`/share`, defaulting to `viewer`,
+ *   or `/share <role>` with a recognized role).
+ * - `invalid` — an unrecognized role argument was given (the caller shows usage).
+ */
+export type ShareCommand = {
+    kind: 'create';
+    role: ShareRole;
+} | {
+    kind: 'invalid';
+    arg: string;
+};
+/**
+ * Type guard for a valid {@link ShareRole} (case-insensitive callers should
+ * lower-case first).
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is one of the {@link SHARE_ROLES}.
+ */
+export declare function isShareRole(value: string): value is ShareRole;
+/**
+ * Parses a `/share [role]` command. Bare `/share` creates a link at the default
+ * `viewer` role; `/share <role>` uses the named role when valid (any case); an
+ * unrecognized role is reported as invalid so the caller can show usage. Returns
+ * `null` when the input is not the `/share` command.
+ *
+ * @param input - The raw chat input.
+ * @returns The parsed {@link ShareCommand}, or `null`.
+ */
+export declare function parseShareCommand(input: string): ShareCommand | null;
+/**
+ * Builds the `POST /projects/:projectId/shares` body for a role.
+ *
+ * @param role - The role to grant (defaults to {@link DEFAULT_SHARE_ROLE}).
+ * @returns The normalized share payload.
+ */
+export declare function buildSharePayload(role?: ShareRole): SharePayload;
+/**
+ * Resolves the copyable public URL for a created share link. Prefers the
+ * backend-supplied `url` (canonical origin / custom domain); otherwise builds
+ * `<origin>/share/<slug>` from the given origin, tolerating a trailing slash.
+ *
+ * @param result - The created link from the share endpoint.
+ * @param origin - The current page origin (e.g. `window.location.origin`).
+ * @returns The absolute, copyable share URL.
+ */
+export declare function buildShareUrl(result: ShareLinkResult, origin: string): string;
+//# sourceMappingURL=chat-share-utilities.d.ts.map

package/dist/components/chat-share-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-share-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-share-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,qDAAsD,CAAA;AAE9E,sCAAsC;AACtC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,EAAE,SAAoB,CAAA;AAErD,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAKvD,CAAA;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,IAAI,EAAE,SAAS,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjG;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,SAA8B,GAAG,YAAY,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI7E"}

package/dist/components/chat-share-utilities.js

@@ -0,0 +1,90 @@
+/**
+ * Pure helpers backing the `/share <role>` command and the header share button.
+ *
+ * `/share` creates a public share link for the current project by POSTing
+ * `{ role }` to `POST /projects/:projectId/shares`. The backend (wired in the
+ * host app) mints a slug-bearing link row and returns it; anyone who opens
+ * `GET /share/:slug` is granted that role — a `viewer` link is an
+ * unauthenticated read. Roles, least- to most-privileged: viewer, commenter,
+ * editor, owner. The default — and the safest — role is `viewer`.
+ *
+ * These helpers parse the command, validate the role against the shared
+ * contract, build the exact POST body, and resolve the copyable public URL from
+ * the response. They are deterministic and side-effect free so they can be unit
+ * tested without rendering or a backend. The role labels are English defaults
+ * the component wraps in `t()` at render.
+ *
+ * @module
+ */
+/**
+ * Share roles, ordered least- to most-privileged. Mirrors the
+ * `@molecule/api-resource-share` `SHARE_ROLES` contract; duplicated here (rather
+ * than imported) because an `app-*` package may not import an `api-*` package
+ * across the stack boundary.
+ */
+export const SHARE_ROLES = ['viewer', 'commenter', 'editor', 'owner'];
+/** The default (and safest) role when `/share` is run with no argument. */
+export const DEFAULT_SHARE_ROLE = 'viewer';
+/** Short English labels per role (the component wraps these in `t()` at render). */
+export const SHARE_ROLE_LABELS = {
+    viewer: 'Viewer — view only',
+    commenter: 'Commenter — view & comment',
+    editor: 'Editor — view & edit',
+    owner: 'Owner — full access',
+};
+/**
+ * Type guard for a valid {@link ShareRole} (case-insensitive callers should
+ * lower-case first).
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is one of the {@link SHARE_ROLES}.
+ */
+export function isShareRole(value) {
+    return SHARE_ROLES.includes(value);
+}
+/**
+ * Parses a `/share [role]` command. Bare `/share` creates a link at the default
+ * `viewer` role; `/share <role>` uses the named role when valid (any case); an
+ * unrecognized role is reported as invalid so the caller can show usage. Returns
+ * `null` when the input is not the `/share` command.
+ *
+ * @param input - The raw chat input.
+ * @returns The parsed {@link ShareCommand}, or `null`.
+ */
+export function parseShareCommand(input) {
+    const match = input.trim().match(/^\/share(?:\s+(.*))?$/i);
+    if (!match)
+        return null;
+    const arg = (match[1] ?? '').trim();
+    if (arg === '')
+        return { kind: 'create', role: DEFAULT_SHARE_ROLE };
+    const lower = arg.toLowerCase();
+    if (isShareRole(lower))
+        return { kind: 'create', role: lower };
+    return { kind: 'invalid', arg };
+}
+/**
+ * Builds the `POST /projects/:projectId/shares` body for a role.
+ *
+ * @param role - The role to grant (defaults to {@link DEFAULT_SHARE_ROLE}).
+ * @returns The normalized share payload.
+ */
+export function buildSharePayload(role = DEFAULT_SHARE_ROLE) {
+    return { role };
+}
+/**
+ * Resolves the copyable public URL for a created share link. Prefers the
+ * backend-supplied `url` (canonical origin / custom domain); otherwise builds
+ * `<origin>/share/<slug>` from the given origin, tolerating a trailing slash.
+ *
+ * @param result - The created link from the share endpoint.
+ * @param origin - The current page origin (e.g. `window.location.origin`).
+ * @returns The absolute, copyable share URL.
+ */
+export function buildShareUrl(result, origin) {
+    if (result.url)
+        return result.url;
+    const trimmedOrigin = origin.replace(/\/+$/, '');
+    return `${trimmedOrigin}/share/${result.slug}`;
+}
+//# sourceMappingURL=chat-share-utilities.js.map

package/dist/components/chat-share-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-share-utilities.js","sourceRoot":"","sources":["../../src/components/chat-share-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAK9E,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAc,QAAQ,CAAA;AAErD,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAA8B;IAC1D,MAAM,EAAE,oBAAoB;IAC5B,SAAS,EAAE,4BAA4B;IACvC,MAAM,EAAE,sBAAsB;IAC9B,KAAK,EAAE,qBAAqB;CAC7B,CAAA;AAoCD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAQ,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAA;IAC1D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACnC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAA;IACnE,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAA;IAC/B,IAAI,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IAC9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAkB,kBAAkB;IACpE,OAAO,EAAE,IAAI,EAAE,CAAA;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAuB,EAAE,MAAc;IACnE,IAAI,MAAM,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,CAAA;IACjC,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAChD,OAAO,GAAG,aAAa,UAAU,MAAM,CAAC,IAAI,EAAE,CAAA;AAChD,CAAC"}

package/dist/components/chat-skills-utilities.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Pure helpers backing the `/skills` browser and the proactive "Relevant skill"
+ * suggestion.
+ *
+ * Following the 2026 Agent Skills folder convention, a skill is a *directory*
+ * under the project's `.agents/skills/` tree whose entry file is `SKILL.md`
+ * (e.g. `.agents/skills/auth/SKILL.md`), carrying a YAML frontmatter block that
+ * declares `name` and `description`. Discovery deliberately matches ONLY those
+ * `SKILL.md` entry files — loose Markdown fragments under `patterns/` and the
+ * `examples/` reference corpus are scaffold support material, NOT user-facing
+ * skills, so surfacing them would bury the real skills (the bug this convention
+ * fixes). These helpers discover skill files via the SAME file-list /
+ * file-content API the chat already uses for `@`-mentions (injected as
+ * functions so this layer stays decoupled from any HTTP client), parse each
+ * skill's metadata, filter the list by a query, and run a lightweight relevance
+ * pass over recent messages so the most relevant skill can be offered with a
+ * one-click load.
+ *
+ * All functions here are deterministic and side-effect free (apart from the
+ * caller-supplied fetchers in {@link loadProjectSkills}), so they can be unit
+ * tested without rendering or a real backend.
+ *
+ * @module
+ */
+/** A discovered project skill. */
+export interface SkillInfo {
+    /** Relative path within the project, e.g. `'.agents/skills/patterns/styling.md'` (no leading slash). */
+    path: string;
+    /** Display name (frontmatter `name`, else first heading, else path-derived). */
+    name: string;
+    /** One-line description (frontmatter `description`, else first paragraph). */
+    description: string;
+}
+/**
+ * Normalizes a file path returned by the file-list API into a project-relative
+ * path: strips a leading `/workspace/` and any leading slash.
+ *
+ * @param path - The raw file path.
+ * @returns The project-relative path.
+ */
+export declare function toRelativePath(path: string): string;
+/**
+ * Whether a path points at a skill's entry file under the 2026 Agent Skills
+ * folder convention: a `SKILL.md` directly inside a skill directory under
+ * `.agents/skills/` (i.e. `.agents/skills/<name>/SKILL.md`). Loose `*.md`
+ * fragments and the reserved `patterns/` + `examples/` support trees are NOT
+ * skills and return `false`. Tolerant of `/workspace/`-prefixed or
+ * leading-slash paths.
+ *
+ * @param path - The file path to test.
+ * @returns `true` if the path is a skill's `SKILL.md` entry file.
+ */
+export declare function isSkillFile(path: string): boolean;
+/**
+ * Derives a fallback skill name from its path: the filename without extension,
+ * or — for the conventional `SKILL.md`/`INDEX.md` entry files — the parent
+ * directory name (which names the skill).
+ *
+ * @param path - The skill file's relative path.
+ * @returns A human-ish name derived from the path.
+ */
+export declare function deriveSkillNameFromPath(path: string): string;
+/**
+ * Slugifies a skill display name into a filesystem-safe directory name for its
+ * folder under `.agents/skills/`: lowercased, with every run of non-alphanumeric
+ * characters collapsed to a single hyphen and surrounding hyphens trimmed. Falls
+ * back to `'new-skill'` when the name has no usable characters, so the derived
+ * path is always valid.
+ *
+ * @param name - The skill's display name.
+ * @returns A safe directory slug for the skill.
+ */
+export declare function slugifySkillName(name: string): string;
+/**
+ * The project-relative path of a new skill's entry file under the 2026 Agent
+ * Skills folder convention: `.agents/skills/<slug>/SKILL.md` (no leading slash),
+ * where `<slug>` is {@link slugifySkillName} of the display name. The result is
+ * exactly the shape {@link isSkillFile} recognizes, so a freshly created skill is
+ * immediately discoverable by the same `/skills` browser.
+ *
+ * @param name - The skill's display name.
+ * @returns The new skill's `SKILL.md` relative path.
+ */
+export declare function newSkillPath(name: string): string;
+/**
+ * Builds the starter `SKILL.md` content for a new skill: a YAML frontmatter
+ * block declaring the `name` and a `description` placeholder (so the skill shows
+ * up — with a clear "edit me" hint — in the `/skills` browser right away),
+ * followed by a short authoring scaffold. The content round-trips through
+ * {@link parseSkillMeta} (the same parser discovery uses), so a created skill's
+ * metadata is identical whether read from this template or re-discovered on disk.
+ *
+ * @param name - The skill's display name (used verbatim as the frontmatter `name`).
+ * @returns The `SKILL.md` file content for a new skill.
+ */
+export declare function buildNewSkillTemplate(name: string): string;
+/**
+ * Extracts a skill's display name and description from its content. Prefers the
+ * frontmatter `name`/`description`; falls back to the first Markdown heading
+ * for the name and the first non-empty body paragraph for the description, and
+ * finally to a path-derived name.
+ *
+ * @param path - The skill file's relative path (used for the name fallback).
+ * @param content - The raw file content (may be empty if it couldn't be read).
+ * @returns The resolved `name` and `description`.
+ */
+export declare function parseSkillMeta(path: string, content: string): {
+    name: string;
+    description: string;
+};
+/**
+ * Filters skills by a free-text query, matching (case-insensitively) against
+ * the name, description, and path. An empty/blank query returns all skills.
+ *
+ * @param skills - The skills to filter.
+ * @param query - The search query.
+ * @returns The matching skills, in input order.
+ */
+export declare function filterSkills(skills: readonly SkillInfo[], query: string): SkillInfo[];
+/**
+ * Discovers and loads every project skill. Uses the injected `fetchList` to get
+ * the project's file paths, keeps the ones under `.agents/skills/`, reads each
+ * via `fetchContent`, parses its metadata, and returns the list sorted by name.
+ *
+ * The fetchers are injected (rather than importing an HTTP client) so this stays
+ * decoupled and unit-testable. A single unreadable skill file is tolerated: it
+ * still appears with a path-derived name and no description.
+ *
+ * @param fetchList - Returns all project file paths.
+ * @param fetchContent - Returns the content of one skill file by relative path.
+ * @returns The discovered skills, sorted by display name.
+ */
+export declare function loadProjectSkills(fetchList: () => Promise<string[]>, fetchContent: (relativePath: string) => Promise<string>): Promise<SkillInfo[]>;
+/** Outcome of one {@link loadProjectSkillsResilient} attempt, used to drive the UI. */
+export interface ResilientSkillsLoad {
+    /** The discovered skills (possibly empty if the sandbox is genuinely skill-less). */
+    skills: SkillInfo[];
+    /**
+     * `true` when every attempt came back with zero skill files (the sandbox is
+     * almost certainly still scaffolding `.agents/skills/`), so the UI should show
+     * a "waiting for the sandbox" state rather than a definitive "no skills" one.
+     */
+    stillBooting: boolean;
+}
+/**
+ * Loads project skills with bounded retry, for the window where a sandbox has
+ * booted far enough to answer the file-list call but has NOT yet materialized
+ * its `.agents/skills/` tree.
+ *
+ * The server announces "Loaded N skills" from a static, always-available source
+ * (its baked-in built-in skill set); the `/skills` browser reads the LIVE
+ * sandbox file list, which is empty until scaffolding finishes. Clicking the
+ * announce card during that gap previously hit a
+ * permanent "No skills found" dead-end. Because a ready sandbox effectively
+ * always has the built-in skills scaffolded, "zero skill files" (or a transient
+ * fetch error) is treated as "still booting" and retried a bounded number of
+ * times before settling — so the skills appear on their own once ready, with an
+ * honest waiting state in between instead of a misleading empty one.
+ *
+ * @param fetchList - Returns all project file paths.
+ * @param fetchContent - Returns the content of one skill file by relative path.
+ * @param options - Retry tuning + injectables for cancellation and tests.
+ * @param options.attempts - Total tries before settling. Defaults to 10.
+ * @param options.delayMs - Delay between tries, in ms. Defaults to 2000.
+ * @param options.sleep - Awaitable delay (injected in tests). Defaults to `setTimeout`.
+ * @param options.isCancelled - Bail-out predicate (e.g. the card was closed).
+ * @param options.onRetry - Invoked before each retry sleep (e.g. to show "waiting").
+ * @returns The discovered skills plus whether the sandbox still looks like it's booting.
+ */
+export declare function loadProjectSkillsResilient(fetchList: () => Promise<string[]>, fetchContent: (relativePath: string) => Promise<string>, options?: {
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    isCancelled?: () => boolean;
+    onRetry?: () => void;
+}): Promise<ResilientSkillsLoad>;
+/** A skill the relevance pass judged relevant to the recent conversation. */
+export interface SkillSuggestion {
+    /** The relevant skill. */
+    skill: SkillInfo;
+    /** Relevance score (higher = more relevant); name matches weigh heavier. */
+    score: number;
+}
+/**
+ * Joins the text of the most recent USER messages into a single relevance
+ * signal. Assistant/system turns are excluded so the suggestion tracks what the
+ * user is actually asking for, not the agent's own verbiage.
+ *
+ * @param messages - Conversation messages (newest last), each with a `role` and `content`.
+ * @param count - How many trailing user messages to include. Defaults to 3.
+ * @returns The concatenated text of the recent user messages.
+ */
+export declare function recentUserText(messages: ReadonlyArray<{
+    role: string;
+    content: string;
+}>, count?: number): string;
+/**
+ * Runs a lightweight relevance pass: scores each skill by how many of its
+ * name/description keywords appear in `recentText` (name matches weigh heavier),
+ * and returns the top matches above a minimum score. Deterministic and
+ * side-effect free, so the caller can recompute it as the conversation grows.
+ *
+ * @param skills - The candidate skills (already excluding loaded/dismissed ones).
+ * @param recentText - Recent conversation text (see {@link recentUserText}).
+ * @param options - Tuning: `max` results (default 1) and `minScore` threshold (default 2).
+ * @param options.max - Maximum number of suggestions to return.
+ * @param options.minScore - Minimum score a skill must reach to be suggested.
+ * @returns The most relevant skills, highest score first (ties broken by name).
+ */
+export declare function suggestRelevantSkills(skills: readonly SkillInfo[], recentText: string, options?: {
+    max?: number;
+    minScore?: number;
+}): SkillSuggestion[];
+/**
+ * The single skill to NUDGE the user to load for the current conversation, or null when there's
+ * nothing useful to suggest. Picks the genuine top match for `recentText` (via
+ * {@link suggestRelevantSkills}) from the candidate pool — all skills minus the ones the user
+ * dismissed or already @-attached — then returns null if that top match is ALREADY LOADED:
+ * either @-loaded this session (`loaded`) OR default-loaded (`defaultLoaded`, its full body
+ * always-on in the system prompt). Suggesting an already-loaded skill just points at context
+ * the agent already has, so we never do it; for a fresh project where every skill is
+ * default-loaded the tip simply never fires. We null the top match (rather than dropping loaded
+ * skills from the pool) so the next-best doesn't immediately pop up — the tip changes only when
+ * the conversation produces a genuinely different top match, never just because the last one got
+ * loaded (the "suggests one after another" parade the user reported).
+ *
+ * @param skills - All discovered project skills.
+ * @param recentText - Recent user text to match against.
+ * @param sets - Exclusion sets, all keyed by skill `path`.
+ * @param sets.dismissed - Skills the user dismissed.
+ * @param sets.attachedPaths - Already-@-attached file paths (leading-slash form, matched against `'/' + skill.path`).
+ * @param sets.loaded - Skills @-loaded this session.
+ * @param sets.defaultLoaded - Default-loaded skills (always-on in the prompt).
+ * @returns The skill to suggest, or null.
+ */
+export declare function pickRelevantSkill(skills: readonly SkillInfo[], recentText: string, sets: {
+    dismissed: ReadonlySet<string>;
+    attachedPaths: ReadonlySet<string>;
+    loaded: ReadonlySet<string>;
+    defaultLoaded: ReadonlySet<string>;
+}): SkillInfo | null;
+//# sourceMappingURL=chat-skills-utilities.d.ts.map

package/dist/components/chat-skills-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-skills-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-skills-utilities.ts"],"names":[],"mappings":"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"}