@almyty/skills 1.0.16 → 1.3.0

package/dist/installer.d.ts

@@ -14,14 +14,37 @@ import type { AgentTarget } from './agents.js';
 export interface InstallResult {
     agent: string;
     skillsDir: string;
+    /** How many skill files were actually written. */
     installed: number;
+    /** How many were refused (unsafe name, or a path outside skillsDir). */
+    skipped: number;
+    /**
+     * How many of the written files replaced an existing SKILL.md.
+     * Installing is a write into someone's editor config, so the count of
+     * files it overwrote is part of the answer, not a detail.
+     */
+    overwritten: number;
+    /** True when nothing was written because this was a dry run. */
+    dryRun: boolean;
     files: string[];
 }
+export interface InstallOptions {
+    /**
+     * Report what would be written and touch nothing. `install` writes
+     * into directories an editor reads on every session; being able to
+     * see the exact paths first is the difference between a tool you
+     * trust and one you run in a scratch clone.
+     */
+    dryRun?: boolean;
+}
 /**
  * Install skill files into an agent's skills directory.
  * Each skill lives at `<skillsDir>/<skill-name>/SKILL.md`.
+ *
+ * With `dryRun`, resolves and validates every path and reports what it
+ * would write, without creating a directory or touching a file.
  */
-export declare function installSkills(skills: SkillFile[], target: AgentTarget): InstallResult;
+export declare function installSkills(skills: SkillFile[], target: AgentTarget, options?: InstallOptions): InstallResult;
 /** Remove every almyty-installed skill from an agent's skills directory. */
 export declare function removeSkills(target: AgentTarget): number;
 /** List almyty-installed skills in an agent's skills directory. */

package/dist/installer.js

@@ -10,12 +10,36 @@
  * already present in every SKILL.md we generate.
  */
 import { writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve, sep } from 'path';
 /** Legacy prefix from <=v1.0.9 — older installs still use this dir
  *  name. Kept here so `remove`/`installed` continue to find them. */
 const LEGACY_SKILL_PREFIX = 'almyty-';
 /** Marker line we expect inside every SKILL.md frontmatter we wrote. */
 const ALMYTY_MARKER = /^\s*author:\s*almyty\s*$/m;
+/**
+ * Skill names come from the backend/gateway and are used to build
+ * filesystem paths under skillsDir. A malicious or compromised gateway
+ * could return `name: "../../../.ssh/authorized_keys"` and have the
+ * installer write — or, via the legacy-dir cleanup, recursively delete —
+ * arbitrary files on the user's machine (and the daemon/watch modes do
+ * this automatically on a timer). Restrict names to a single safe path
+ * segment.
+ */
+const SAFE_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function isSafeSkillName(name) {
+    return (typeof name === 'string' &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.includes('/') &&
+        !name.includes('\\') &&
+        SAFE_SKILL_NAME.test(name));
+}
+/** Defence in depth: assert a built path stays inside skillsDir. */
+function isInside(baseDir, candidate) {
+    const base = resolve(baseDir);
+    const target = resolve(candidate);
+    return target === base || target.startsWith(base + sep);
+}
 /**
  * Strip the legacy `name: almyty-<x>` line in the SKILL.md frontmatter
  * to `name: <x>` so the agent-visible identifier is the skill's own
@@ -46,11 +70,24 @@ function isAlmytyInstall(skillsDir, dirName) {
 /**
  * Install skill files into an agent's skills directory.
  * Each skill lives at `<skillsDir>/<skill-name>/SKILL.md`.
+ *
+ * With `dryRun`, resolves and validates every path and reports what it
+ * would write, without creating a directory or touching a file.
  */
-export function installSkills(skills, target) {
+export function installSkills(skills, target, options = {}) {
+    const dryRun = options.dryRun === true;
     const files = [];
-    mkdirSync(target.skillsDir, { recursive: true });
+    let overwritten = 0;
+    if (!dryRun)
+        mkdirSync(target.skillsDir, { recursive: true });
     for (const skill of skills) {
+        // Reject backend-supplied names that aren't a single safe path
+        // segment — skip rather than throw so one bad entry can't break the
+        // whole install (e.g. in daemon/watch mode).
+        if (!isSafeSkillName(skill.name)) {
+            console.warn(`Skipping skill with unsafe name: ${JSON.stringify(skill.name)}`);
+            continue;
+        }
         const dirName = skill.name;
         const skillDir = join(target.skillsDir, dirName);
         const skillFile = join(skillDir, 'SKILL.md');
@@ -58,6 +95,17 @@ export function installSkills(skills, target) {
         // shape, remove it before writing the new shape so the agent
         // doesn't see two copies of the same skill.
         const legacyDir = join(target.skillsDir, `${LEGACY_SKILL_PREFIX}${skill.name}`);
+        // Containment guard (defence in depth) before any write/delete.
+        if (!isInside(target.skillsDir, skillDir) || !isInside(target.skillsDir, legacyDir)) {
+            console.warn(`Skipping skill whose path escapes the skills directory: ${skill.name}`);
+            continue;
+        }
+        if (existsSync(skillFile))
+            overwritten++;
+        if (dryRun) {
+            files.push(skillFile);
+            continue;
+        }
         if (legacyDir !== skillDir && existsSync(legacyDir)) {
             rmSync(legacyDir, { recursive: true, force: true });
         }
@@ -68,7 +116,14 @@ export function installSkills(skills, target) {
     return {
         agent: target.name,
         skillsDir: target.skillsDir,
-        installed: skills.length,
+        // What was written, not what was offered. The loop skips skills with
+        // an unsafe name or a path that escapes the skills directory, and
+        // counting the input meant "Installed 12 skill files" for ten files
+        // on disk -- the two that were refused were reported as installed.
+        installed: files.length,
+        skipped: skills.length - files.length,
+        overwritten,
+        dryRun,
         files,
     };
 }

package/dist/meta-skill.d.ts

@@ -1,2 +1,11 @@
 import type { SkillFile } from './client.js';
+/**
+ * The one skill the daemon always installs: how to reach the rest.
+ *
+ * It is read by a coding agent, so every command in it has to exist.
+ * It documented `install`, `list`, `search`, `run` and `daemon` only,
+ * and wrote refs with a mandatory leading `@` the CLI treats as
+ * optional — so an agent copying it out learned a surface that was
+ * both smaller and subtly wrong.
+ */
 export declare function generateMetaSkill(): SkillFile;

package/dist/meta-skill.js

@@ -1,3 +1,12 @@
+/**
+ * The one skill the daemon always installs: how to reach the rest.
+ *
+ * It is read by a coding agent, so every command in it has to exist.
+ * It documented `install`, `list`, `search`, `run` and `daemon` only,
+ * and wrote refs with a mandatory leading `@` the CLI treats as
+ * optional — so an agent copying it out learned a surface that was
+ * both smaller and subtly wrong.
+ */
 export function generateMetaSkill() {
     const content = `---
 name: almyty-skills
@@ -13,16 +22,30 @@ Manage API skills powered by almyty — a universal API-to-AI tool gateway.
 
 ## When to use
 
-- User wants to discover available API tools
-- User wants to find a specific API capability
-- User wants to run an API tool directly
-- User needs to list what skills are installed
+- The user wants to discover available API tools
+- The user wants to find a specific API capability
+- The user wants to run an API tool directly
+- The user needs to know which skills are installed here
+
+## References
+
+A skill is addressed as \`org/gateway/skill\`, a whole gateway as
+\`org/gateway\`. A leading \`@\` is optional. A bare name is treated as a
+search and installs only when it matches exactly one skill.
 
 ## Commands
 
-### List all available skills
+Add \`--json\` to any read command for parseable output.
+
+### What gateways exist
+\`\`\`bash
+npx @almyty/skills gateways
+\`\`\`
+
+### List available skills
 \`\`\`bash
 npx @almyty/skills list
+npx @almyty/skills list acme/petstore
 \`\`\`
 
 ### Search for skills
@@ -30,20 +53,33 @@ npx @almyty/skills list
 npx @almyty/skills search <query>
 \`\`\`
 
-### Install a specific skill
+### Install skills (writes SKILL.md into this project's agent dirs)
 \`\`\`bash
-npx @almyty/skills install @<org>/<gateway>/<skill-name>
+npx @almyty/skills install acme/petstore --dry-run   # show the exact files first
+npx @almyty/skills install acme/petstore/get-pet
 \`\`\`
 
 ### Run a skill directly
 \`\`\`bash
-npx @almyty/skills run @<org>/<gateway>/<skill-name> --param1 value1 --param2 value2
+npx @almyty/skills run acme/petstore/get-pet --petId 123
 \`\`\`
 
-### Start the skill daemon (auto-syncs all skills)
+### What is installed here, and undo it
 \`\`\`bash
-npx @almyty/skills daemon
+npx @almyty/skills installed
+npx @almyty/skills remove
 \`\`\`
+
+### Keep skills in sync on a timer
+\`\`\`bash
+npx @almyty/skills daemon              # every gateway
+npx @almyty/skills watch acme/petstore # one gateway
+\`\`\`
+
+## Exit codes
+
+\`2\` usage error, \`3\` not authenticated (run \`npx @almyty/auth login\`),
+\`4\` no such gateway or skill, \`5\` the skill ran and failed.
 `;
     return {
         name: 'skills',

package/dist/target-selector.d.ts

@@ -13,6 +13,13 @@ export interface SelectionInput {
     yes?: boolean;
     /** `--global` / `-G`: include / prefer home-scope installs. */
     global?: boolean;
+    /**
+     * Whether prompting is allowed. The caller decides (see tty.ts):
+     * reading `process.stdin.isTTY` here meant a CI runner's pseudo-tty
+     * counted as interactive, and a scripted install could hang on a
+     * picker with nobody to answer it.
+     */
+    interactive?: boolean;
     /** Override $HOME (test seam). */
     home?: string;
 }

package/dist/target-selector.js

@@ -187,12 +187,14 @@ export function selectInstallTargetsAuto(input) {
             return dedupeBySkillsDir([...matched, universalTarget(projectDir)]);
         }
     }
-    // 6. `--yes` / non-TTY: pick a sensible default WITHOUT prompting.
-    //    Project-detected + universal first; if nothing project-side,
-    //    show home-detected as a hint (the user probably wants the
-    //    interactive picker for this; here we just return defaults
-    //    so scripted use doesn't hang).
-    if (yes || !process.stdin.isTTY) {
+    // 6. `--yes`, or nowhere to prompt: pick a sensible default WITHOUT
+    //    prompting. Project-detected + universal first; if nothing
+    //    project-side, fall back to the defaults so scripted use never
+    //    hangs on a picker.
+    //
+    //    `interactive` comes from the caller rather than from
+    //    process.stdin.isTTY, which is true inside most CI runners.
+    if (yes || input.interactive === false) {
         const projectDetected = detectAgents(projectDir);
         if (projectDetected.length > 0) {
             return dedupeBySkillsDir([

package/dist/tty.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether this process may prompt, and whether it may colour.
+ *
+ * `install` used to decide interactivity from `process.stdin.isTTY`
+ * alone. That is true inside most CI runners' pseudo-terminals, so a
+ * scripted install could stop dead on a multi-select picker nobody was
+ * there to answer. Both streams and the CI marker have to agree before
+ * a prompt is allowed.
+ */
+/** Whether both stdio streams are terminals. A test seam. */
+export interface TtyState {
+    stdin: boolean;
+    stdout: boolean;
+}
+export declare function isInteractive(env?: NodeJS.ProcessEnv, tty?: TtyState): boolean;
+/**
+ * Whether decoration is wanted. Honours NO_COLOR (any value) and
+ * FORCE_COLOR, in that order of surprise — see https://no-color.org.
+ * The prompt library reads the same variables, so setting NO_COLOR
+ * gives a plain picker rather than a half-coloured one.
+ */
+export declare function useColor(env?: NodeJS.ProcessEnv, tty?: TtyState): boolean;

package/dist/tty.js

@@ -0,0 +1,35 @@
+/**
+ * Whether this process may prompt, and whether it may colour.
+ *
+ * `install` used to decide interactivity from `process.stdin.isTTY`
+ * alone. That is true inside most CI runners' pseudo-terminals, so a
+ * scripted install could stop dead on a multi-select picker nobody was
+ * there to answer. Both streams and the CI marker have to agree before
+ * a prompt is allowed.
+ */
+function currentTty() {
+    return {
+        stdin: Boolean(process.stdin.isTTY),
+        stdout: Boolean(process.stdout.isTTY),
+    };
+}
+export function isInteractive(env = process.env, tty = currentTty()) {
+    if (env.ALMYTY_NON_INTERACTIVE === '1')
+        return false;
+    if (env.CI && env.CI !== 'false' && env.CI !== '0')
+        return false;
+    return tty.stdin && tty.stdout;
+}
+/**
+ * Whether decoration is wanted. Honours NO_COLOR (any value) and
+ * FORCE_COLOR, in that order of surprise — see https://no-color.org.
+ * The prompt library reads the same variables, so setting NO_COLOR
+ * gives a plain picker rather than a half-coloured one.
+ */
+export function useColor(env = process.env, tty = currentTty()) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0')
+        return true;
+    return tty.stdout;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function readVersion(fallback?: string): string;
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,22 @@
+/**
+ * The CLI's own version, read from its package.json at startup.
+ *
+ * It used to be a hardcoded string, which drifted: `--version`
+ * answered 0.1.0 while the published package was 1.2.0, so a bug
+ * report never identified the build it came from. Both `dist/index.js`
+ * and `src/index.ts` sit one directory below the package root, so the
+ * same relative path resolves for the built bin and for `tsx src/index.ts`.
+ */
+import { readFileSync } from 'node:fs';
+export function readVersion(fallback = '0.0.0') {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        return typeof pkg.version === 'string' && pkg.version.length > 0
+            ? pkg.version
+            : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export const VERSION = readVersion();

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@almyty/skills",
-  "version": "1.0.16",
-  "description": "Install API skills into AI coding agents — Claude Code, Cursor, Windsurf, Copilot, Codex",
+  "version": "1.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Install any API as a skill into Claude Code, Cursor, Windsurf, Copilot, or Codex — almyty turns OpenAPI and GraphQL into agent-ready skills.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -30,9 +33,9 @@
     "almyty"
   ],
   "author": "almyty",
-  "license": "BSL-1.1",
+  "license": "Apache-2.0",
   "dependencies": {
-    "@almyty/client": "^0.1.0",
+    "@almyty/client": "^1.2.0",
     "@clack/prompts": "^1.2.0"
   },
   "devDependencies": {
@@ -40,5 +43,17 @@
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "vitest": "^4.1.0"
+  },
+  "homepage": "https://almyty.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almyty-inc/almyty.git",
+    "directory": "packages/skills-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/almyty-inc/almyty/issues"
+  },
+  "overrides": {
+    "postcss": "^8.5.23"
   }
 }