@testspectra/skills 1.1.8-rc.9 → 1.1.11-rc.3

package/README.md

@@ -50,16 +50,16 @@ overrides the saved selection for a single invocation.
 
 ## Available Skills
 
-| Skill | Covers |
-| :--- | :--- |
-| `workspace-structure` | Directory layout, zero-import architecture, file suffixes, `spectra.config.ts`, core CLI commands |
-| `spec-and-suite-authoring` | `suite.md` / `spec.md` frontmatter, the paired `*.test.ts` script, every `spectra lint` rule |
-| `page-objects-and-selectors` | Page Object pattern (`Spectra.get`/`getAll`), the `~`/`#` selector contract |
-| `matchers-and-assertions` | Full element action/assertion/collection matcher and global `Spectra.*` command reference |
-| `shared-steps-and-actions` | `Step.*` business workflows vs `support/actions/*` technical utilities |
-| `lifecycle-hooks` | `global-hooks/` vs `specs/<suite>/hooks/`, execution order, failure cascade |
-| `fixtures-data` | `fixtures/*.json` and the ambient `Fixture.*` namespace |
-| `network-interception` | `Spectra.intercept()` mocking, polling, and failure-simulation patterns |
+| Skill                        | Covers                                                                                            |
+| :--------------------------- | :------------------------------------------------------------------------------------------------ |
+| `workspace-structure`        | Directory layout, zero-import architecture, file suffixes, `spectra.config.ts`, core CLI commands |
+| `spec-and-suite-authoring`   | `suite.md` / `spec.md` frontmatter, the paired `*.test.ts` script, every `spectra lint` rule      |
+| `page-objects-and-selectors` | Page Object pattern (`Spectra.get`/`getAll`), the `~`/`#` selector contract                       |
+| `matchers-and-assertions`    | Full element action/assertion/collection matcher and global `Spectra.*` command reference         |
+| `shared-steps-and-actions`   | `Step.*` business workflows vs `support/actions/*` technical utilities                            |
+| `lifecycle-hooks`            | `global-hooks/` vs `specs/<suite>/hooks/`, execution order, failure cascade                       |
+| `fixtures-data`              | `fixtures/*.json` and the ambient `Fixture.*` namespace                                           |
+| `network-interception`       | `Spectra.intercept()` mocking, polling, and failure-simulation patterns                           |
 
 Each skill is grounded in `docs/v2/` and the reference workspace at `cli/templates/default`, so an
 AI coding agent scaffolding TestSpectra scripts produces code that already passes `spectra lint`.

package/dist/commands/add.js

@@ -1,6 +1,6 @@
 // oxlint-disable no-console
 import { intro, outro, multiselect, isCancel, cancel } from '@clack/prompts';
-import { installSkill } from '../detector.js';
+import { installSkill, addConfiguredSkills } from '../detector.js';
 import { loadAllSkills, getSkill } from '../registry.js';
 export async function addSkills(skillIds, baseDir = process.cwd(), agentIds) {
     intro('\x1b[1m\x1b[36m➕ Install TestSpectra Script-Authoring Skills\x1b[0m');
@@ -36,6 +36,7 @@ export async function addSkills(skillIds, baseDir = process.cwd(), agentIds) {
         }
     }
     if (installedList.length > 0) {
+        addConfiguredSkills(baseDir, installedList);
         outro(`\x1b[32mSuccessfully installed ${installedList.length} skill(s)!\x1b[0m`);
     }
     else {

package/dist/commands/init.js

@@ -1,6 +1,6 @@
 // oxlint-disable no-console
 import { intro, outro, multiselect, isCancel, cancel } from '@clack/prompts';
-import { KNOWN_AGENTS, writeAgentConfig, installSkill } from '../detector.js';
+import { KNOWN_AGENTS, writeAgentConfig, installSkill, addConfiguredSkills } from '../detector.js';
 import { loadAllSkills, getSkill } from '../registry.js';
 export async function initSkills(baseDir = process.cwd()) {
     intro('\x1b[1m\x1b[36m🧭 TestSpectra Skills Setup\x1b[0m');
@@ -50,5 +50,8 @@ export async function initSkills(baseDir = process.cwd()) {
             console.log(`  \x1b[32m✔\x1b[0m Installed \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
         }
     }
+    if (installedList.length > 0) {
+        addConfiguredSkills(baseDir, installedList);
+    }
     outro(`\x1b[32mSetup complete!\x1b[0m Installed ${installedList.length} skill(s) for agent(s): ${agentIds.join(', ')}.`);
 }

package/dist/commands/list.js

@@ -1,11 +1,12 @@
 // oxlint-disable no-console
 import { intro, outro } from '@clack/prompts';
-import { getAgentSkillDirs, isSkillInstalled } from '../detector.js';
+import { getAgentSkillDirs, isSkillInstalled, readConfiguredSkills } from '../detector.js';
 import { loadAllSkills } from '../registry.js';
 export function listSkills(baseDir = process.cwd(), agentIds) {
     intro('\x1b[1m\x1b[36m📦 TestSpectra Skills Registry\x1b[0m');
     const allSkills = loadAllSkills();
     const targetDirs = getAgentSkillDirs(baseDir, agentIds);
+    const configured = new Set(readConfiguredSkills(baseDir) ?? []);
     if (allSkills.length === 0) {
         console.log('No skills found in registry.');
         outro('Done.');
@@ -13,7 +14,7 @@ export function listSkills(baseDir = process.cwd(), agentIds) {
     }
     console.log(`\nAgent directories: \x1b[2m${targetDirs.join(', ')}\x1b[0m\n`);
     for (const skill of allSkills) {
-        const installed = isSkillInstalled(skill.id, baseDir, agentIds);
+        const installed = configured.has(skill.id) || isSkillInstalled(skill.id, baseDir, agentIds);
         const statusBadge = installed ? '\x1b[32m[Installed]\x1b[0m' : '\x1b[90m[Available]\x1b[0m';
         console.log(`  ${statusBadge} \x1b[1m${skill.id}\x1b[0m`);
         console.log(`    \x1b[90m${skill.description}\x1b[0m\n`);

package/dist/commands/remove.js

@@ -1,6 +1,6 @@
 // oxlint-disable no-console
 import { intro, outro } from '@clack/prompts';
-import { removeSkill } from '../detector.js';
+import { removeSkill, removeConfiguredSkills } from '../detector.js';
 export function removeSkills(skillIds, baseDir = process.cwd(), agentIds) {
     intro('\x1b[1m\x1b[31m🗑️  Remove TestSpectra Skills\x1b[0m');
     const targets = skillIds.filter(Boolean);
@@ -22,5 +22,8 @@ export function removeSkills(skillIds, baseDir = process.cwd(), agentIds) {
             console.log(`  \x1b[90m- Skill "${id}" was not installed.\x1b[0m`);
         }
     }
+    if (removedList.length > 0) {
+        removeConfiguredSkills(baseDir, removedList);
+    }
     outro(`\x1b[32mCompleted. Removed ${removedList.length} skill(s).\x1b[0m`);
 }

package/dist/commands/update.js

@@ -1,15 +1,32 @@
 // oxlint-disable no-console
 import { intro, outro } from '@clack/prompts';
-import { getInstalledSkills, installSkill } from '../detector.js';
-import { getSkill } from '../registry.js';
+import { addConfiguredSkills, getInstalledSkills, installSkill, readConfiguredSkills } from '../detector.js';
+import { getSkill, loadAllSkills } from '../registry.js';
 export function updateSkills(skillIds = [], baseDir = process.cwd(), agentIds) {
     intro('\x1b[1m\x1b[36m🔄 Update TestSpectra Skills\x1b[0m');
-    let targets = skillIds.filter(Boolean);
-    if (targets.length === 0) {
-        targets = getInstalledSkills(baseDir, agentIds);
+    const allSkills = loadAllSkills();
+    const knownSkillIds = new Set(allSkills.map((s) => s.id));
+    const explicitTargets = skillIds.filter(Boolean);
+    const isExplicit = explicitTargets.length > 0;
+    // Determine which skills to update:
+    // 1. Explicit skill IDs if provided
+    // 2. Configured skill IDs from .spectra-skills.json (filtered against registry)
+    // 3. Fallback to installed directory detection (filtered against registry)
+    let targets;
+    if (isExplicit) {
+        targets = explicitTargets;
+    }
+    else {
+        const configuredSkills = readConfiguredSkills(baseDir);
+        if (configuredSkills && configuredSkills.length > 0) {
+            targets = configuredSkills.filter((id) => knownSkillIds.has(id));
+        }
+        else {
+            targets = getInstalledSkills(baseDir, agentIds).filter((id) => knownSkillIds.has(id));
+        }
     }
     if (targets.length === 0) {
-        console.log('No installed skills found in project to update.');
+        console.log('No installed TestSpectra skills found in project to update.');
         outro('Done.');
         return;
     }
@@ -17,7 +34,9 @@ export function updateSkills(skillIds = [], baseDir = process.cwd(), agentIds) {
     for (const id of targets) {
         const skill = getSkill(id);
         if (!skill) {
-            console.log(`\x1b[33m⚠️  Skill "${id}" not found in current registry.\x1b[0m`);
+            if (isExplicit) {
+                console.log(`\x1b[33m⚠️  Skill "${id}" not found in current registry.\x1b[0m`);
+            }
             continue;
         }
         const paths = installSkill(skill, baseDir, agentIds);
@@ -26,5 +45,8 @@ export function updateSkills(skillIds = [], baseDir = process.cwd(), agentIds) {
             console.log(`  \x1b[32m✔\x1b[0m Updated \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
         }
     }
+    if (updatedList.length > 0) {
+        addConfiguredSkills(baseDir, updatedList);
+    }
     outro(`\x1b[32mSuccessfully updated ${updatedList.length} skill(s)!\x1b[0m`);
 }

package/dist/detector.d.ts

@@ -10,10 +10,25 @@ export interface AgentDefinition {
  */
 export declare const KNOWN_AGENTS: AgentDefinition[];
 export declare function getKnownAgentIds(): string[];
+export declare const CONFIG_FILENAME = ".spectra-skills.json";
+export interface SkillsConfig {
+    agents?: string[];
+    skills?: string[];
+}
+/** Reads the skills and agent selection persisted in `.spectra-skills.json`, if any. */
+export declare function readSkillsConfig(baseDir?: string): SkillsConfig;
+/** Persists partial skills configuration in `.spectra-skills.json`. */
+export declare function writeSkillsConfig(baseDir: string, patch: Partial<SkillsConfig>): string;
 /** Reads the agent selection persisted by `spectra-skills init`, if any. */
 export declare function readAgentConfig(baseDir?: string): string[] | undefined;
 /** Persists the agent selection chosen via `spectra-skills init` for future add/update/remove/list calls. */
 export declare function writeAgentConfig(baseDir: string, agentIds: string[]): string;
+/** Reads the installed skill IDs recorded in `.spectra-skills.json`, if any. */
+export declare function readConfiguredSkills(baseDir?: string): string[] | undefined;
+/** Adds skill IDs to `.spectra-skills.json`. */
+export declare function addConfiguredSkills(baseDir: string, skillIds: string[]): void;
+/** Removes skill IDs from `.spectra-skills.json`. */
+export declare function removeConfiguredSkills(baseDir: string, skillIds: string[]): void;
 /** Splits a comma/whitespace separated --agent value and reports any id not in KNOWN_AGENTS. */
 export declare function resolveAgentSelection(raw?: string): {
     ids: string[];

package/dist/detector.js

@@ -19,28 +19,70 @@ export const KNOWN_AGENTS = [
 export function getKnownAgentIds() {
     return KNOWN_AGENTS.map((a) => a.id);
 }
-const CONFIG_FILENAME = '.spectra-skills.json';
-/** Reads the agent selection persisted by `spectra-skills init`, if any. */
-export function readAgentConfig(baseDir = process.cwd()) {
+export const CONFIG_FILENAME = '.spectra-skills.json';
+/** Reads the skills and agent selection persisted in `.spectra-skills.json`, if any. */
+export function readSkillsConfig(baseDir = process.cwd()) {
     const configPath = path.join(baseDir, CONFIG_FILENAME);
     if (!fs.existsSync(configPath))
-        return undefined;
+        return {};
     try {
         const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
         const known = new Set(getKnownAgentIds());
         const agents = (parsed.agents ?? []).filter((id) => known.has(id));
-        return agents.length > 0 ? agents : undefined;
+        const skills = Array.isArray(parsed.skills) ? parsed.skills.filter(Boolean) : undefined;
+        return {
+            agents: agents.length > 0 ? agents : undefined,
+            skills,
+        };
     }
     catch {
-        return undefined;
+        return {};
     }
 }
-/** Persists the agent selection chosen via `spectra-skills init` for future add/update/remove/list calls. */
-export function writeAgentConfig(baseDir, agentIds) {
+/** Persists partial skills configuration in `.spectra-skills.json`. */
+export function writeSkillsConfig(baseDir, patch) {
     const configPath = path.join(baseDir, CONFIG_FILENAME);
-    fs.writeFileSync(configPath, JSON.stringify({ agents: agentIds }, null, 2) + '\n', 'utf-8');
+    const existing = readSkillsConfig(baseDir);
+    const updated = {
+        agents: patch.agents !== undefined ? patch.agents : existing.agents,
+        skills: patch.skills !== undefined ? patch.skills : existing.skills,
+    };
+    const out = {};
+    if (updated.agents && updated.agents.length > 0)
+        out.agents = updated.agents;
+    if (updated.skills && updated.skills.length > 0)
+        out.skills = updated.skills;
+    fs.writeFileSync(configPath, JSON.stringify(out, null, 2) + '\n', 'utf-8');
     return configPath;
 }
+/** Reads the agent selection persisted by `spectra-skills init`, if any. */
+export function readAgentConfig(baseDir = process.cwd()) {
+    return readSkillsConfig(baseDir).agents;
+}
+/** Persists the agent selection chosen via `spectra-skills init` for future add/update/remove/list calls. */
+export function writeAgentConfig(baseDir, agentIds) {
+    return writeSkillsConfig(baseDir, { agents: agentIds });
+}
+/** Reads the installed skill IDs recorded in `.spectra-skills.json`, if any. */
+export function readConfiguredSkills(baseDir = process.cwd()) {
+    return readSkillsConfig(baseDir).skills;
+}
+/** Adds skill IDs to `.spectra-skills.json`. */
+export function addConfiguredSkills(baseDir, skillIds) {
+    const existing = new Set(readConfiguredSkills(baseDir) ?? []);
+    for (const id of skillIds) {
+        existing.add(id);
+    }
+    writeSkillsConfig(baseDir, { skills: Array.from(existing).sort() });
+}
+/** Removes skill IDs from `.spectra-skills.json`. */
+export function removeConfiguredSkills(baseDir, skillIds) {
+    const existing = new Set(readConfiguredSkills(baseDir) ?? []);
+    for (const id of skillIds) {
+        existing.delete(id);
+    }
+    writeSkillsConfig(baseDir, { skills: Array.from(existing).sort() });
+}
 /** Splits a comma/whitespace separated --agent value and reports any id not in KNOWN_AGENTS. */
 export function resolveAgentSelection(raw) {
     if (!raw)

package/dist/registry.js

@@ -19,10 +19,7 @@ function parseSkillContent(id, content) {
 }
 function findSkillsDir() {
     // dist/registry.js -> ../skills ; src/registry.ts (ts-node/dev) -> ../skills
-    const candidates = [
-        path.resolve(__dirname, '../skills'),
-        path.resolve(__dirname, '../../skills'),
-    ];
+    const candidates = [path.resolve(__dirname, '../skills'), path.resolve(__dirname, '../../skills')];
     return candidates.find((dir) => fs.existsSync(dir));
 }
 export function loadAllSkills() {

package/dist/skills/matchers-and-assertions/SKILL.md

@@ -103,16 +103,16 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 
 ## 5. Global `Spectra.*` Commands
 
-| Category       | Syntax                                                                                                   |
-| :------------- | :------------------------------------------------------------------------------------------------------- |
-| Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                             |
+| Category       | Syntax                                                                                                                           |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                                                     |
 | Element query  | `Spectra.get(selector)` / `Spectra.getAll(selector)` — chain `.get()`/`.getAll()` on the result to scope a lookup, see section 4 |
-| Window         | `await Spectra.setViewport(1920, 1080)`                                                                  |
-| Timing         | `await Spectra.wait(1000)`                                                                               |
-| Keyboard       | `await Spectra.pressKey("Enter")`                                                                        |
-| Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                               |
-| Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                              |
-| Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill |
+| Window         | `await Spectra.setViewport(1920, 1080)`                                                                                          |
+| Timing         | `await Spectra.wait(1000)`                                                                                                       |
+| Keyboard       | `await Spectra.pressKey("Enter")`                                                                                                |
+| Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                                                       |
+| Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                                                      |
+| Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill                         |
 
 ## 6. `Spectra.browser.*` — Browser/Context Level
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/skills",
-  "version": "1.1.8-rc.9",
+  "version": "1.1.11-rc.3",
   "description": "Installer & manager for modular AI agent skills that standardize TestSpectra script authoring (specs, page objects, steps, actions, hooks, fixtures, matchers)",
   "keywords": [
     "agents",

package/skills/matchers-and-assertions/SKILL.md

@@ -103,16 +103,16 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 
 ## 5. Global `Spectra.*` Commands
 
-| Category       | Syntax                                                                                                   |
-| :------------- | :------------------------------------------------------------------------------------------------------- |
-| Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                             |
+| Category       | Syntax                                                                                                                           |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                                                     |
 | Element query  | `Spectra.get(selector)` / `Spectra.getAll(selector)` — chain `.get()`/`.getAll()` on the result to scope a lookup, see section 4 |
-| Window         | `await Spectra.setViewport(1920, 1080)`                                                                  |
-| Timing         | `await Spectra.wait(1000)`                                                                               |
-| Keyboard       | `await Spectra.pressKey("Enter")`                                                                        |
-| Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                               |
-| Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                              |
-| Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill |
+| Window         | `await Spectra.setViewport(1920, 1080)`                                                                                          |
+| Timing         | `await Spectra.wait(1000)`                                                                                                       |
+| Keyboard       | `await Spectra.pressKey("Enter")`                                                                                                |
+| Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                                                       |
+| Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                                                      |
+| Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill                         |
 
 ## 6. `Spectra.browser.*` — Browser/Context Level