@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.10

package/dist/skill/agents-md.js

@@ -0,0 +1,62 @@
+/**
+ * Managed AGENTS.md block for agents without a SKILL.md convention.
+ *
+ * Cloud agents (Devin, Jules, Copilot coding agent) and guideline-only tools
+ * (Junie, Comate, CodeArts, Windsurf, Kiro steering) read repository-level
+ * AGENTS.md. `pxbaas skill install --scope project --agents-md` writes a small
+ * marker-delimited block pointing at the exported skill directories and
+ * `pxbaas guide`. Everything outside the markers is never touched, and the
+ * block is idempotently replaced on re-install.
+ */
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const AGENTS_MD_FILE = 'AGENTS.md';
+export const BEGIN_MARKER = '<!-- BEGIN pxbaas-skills (managed by pxbaas skill install; do not edit) -->';
+export const END_MARKER = '<!-- END pxbaas-skills -->';
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function blockRegex() {
+    return new RegExp(`\\n*${escapeRe(BEGIN_MARKER)}[\\s\\S]*?${escapeRe(END_MARKER)}\\n*`);
+}
+export function renderBlock(lines) {
+    return [BEGIN_MARKER, ...lines, END_MARKER].join('\n');
+}
+export async function upsertAgentsMdBlock(projectRoot, lines) {
+    const path = join(projectRoot, AGENTS_MD_FILE);
+    const block = renderBlock(lines);
+    if (!existsSync(path)) {
+        await writeFile(path, `${block}\n`, 'utf8');
+        return { path, created: true };
+    }
+    const content = await readFile(path, 'utf8');
+    const updated = blockRegex().test(content)
+        ? content.replace(blockRegex(), `${block}\n`)
+        : `${content.replace(/\s*$/, '')}\n\n${block}\n`;
+    await writeFile(path, updated, 'utf8');
+    return { path, created: false };
+}
+export async function removeAgentsMdBlock(projectRoot) {
+    const path = join(projectRoot, AGENTS_MD_FILE);
+    if (!existsSync(path))
+        return { path, removed: false, deletedFile: false };
+    const content = await readFile(path, 'utf8');
+    if (!blockRegex().test(content))
+        return { path, removed: false, deletedFile: false };
+    const stripped = content.replace(blockRegex(), '');
+    if (stripped.trim() === '') {
+        await rm(path);
+        return { path, removed: true, deletedFile: true };
+    }
+    await writeFile(path, stripped, 'utf8');
+    return { path, removed: true, deletedFile: false };
+}
+export async function agentsMdBlockPresent(projectRoot) {
+    const path = join(projectRoot, AGENTS_MD_FILE);
+    if (!existsSync(path))
+        return false;
+    const content = await readFile(path, 'utf8');
+    return blockRegex().test(content);
+}
+//# sourceMappingURL=agents-md.js.map

package/dist/skill/agents-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../src/skill/agents-md.ts"],"names":[],"mappings":"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"}

package/dist/skill/assets.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Locate the bundled Agent Skills at runtime.
+ *
+ * Distribution route A (ctxdb0-style): skills ship as package files under
+ * `apps/baas/skills/<skill>/` and `package.json#files` includes `skills`.
+ * We resolve the package root by walking up from this module until we find a
+ * `skills/` directory containing at least one `<skill>/SKILL.md`. This works for
+ * the compiled layout (`dist/skill/assets.js`) and for direct source execution.
+ *
+ * There can be MULTIPLE bundled skills (e.g. `pxbaas-cli`, `pxbaas-app-spec`);
+ * `pxbaas skill install` installs all of them by default.
+ *
+ * NOTE: the standalone single-file binary (`bun build --compile`) does not carry
+ * these files on disk; resolution then fails and callers surface a clear
+ * "requires the npm/source install" error.
+ */
+/** Thrown when the bundled skills cannot be located (e.g. single-binary mode). */
+export declare class SkillAssetsNotFoundError extends Error {
+    constructor(message: string);
+}
+/** Walk up from the current module to find the app package root (holds `skills/`). */
+export declare function resolvePackageRoot(startDir?: string): string | null;
+/** Absolute path to the bundled `skills/` directory. */
+export declare function resolveSkillsRoot(startDir?: string): string;
+/** Names of all bundled skills under a given `skills/` root (subdirs with a SKILL.md). */
+export declare function listBundledSkillsIn(skillsRoot: string): Promise<string[]>;
+/** Names of all bundled skills (subdirs of the resolved `skills/` that contain a SKILL.md). */
+export declare function listBundledSkills(startDir?: string): Promise<string[]>;
+/** Absolute path to one bundled skill directory. */
+export declare function resolveSkillAssetDir(skillName: string, startDir?: string): string;
+/** Read the CLI version from the resolved package.json (best-effort). */
+export declare function readCliVersion(startDir?: string): Promise<string>;
+/**
+ * Recursively list a skill's files as POSIX-style relative paths (e.g. `SKILL.md`,
+ * `references/db-and-meta.md`). Skips hidden files/dirs and `node_modules`.
+ */
+export declare function listSkillFiles(assetDir: string): Promise<string[]>;
+//# sourceMappingURL=assets.d.ts.map

package/dist/skill/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/skill/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,kFAAkF;AAClF,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAUD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,MAAoB,GAAG,MAAM,GAAG,IAAI,CAShF;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAoB,GAAG,MAAM,CAQxE;AAED,0FAA0F;AAC1F,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ/E;AAED,+FAA+F;AAC/F,wBAAsB,iBAAiB,CAAC,QAAQ,GAAE,MAAoB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEzF;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAoB,GAAG,MAAM,CAE9F;AAED,yEAAyE;AACzE,wBAAsB,cAAc,CAAC,QAAQ,GAAE,MAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CASpF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBxE"}

package/dist/skill/assets.js

@@ -0,0 +1,111 @@
+/**
+ * Locate the bundled Agent Skills at runtime.
+ *
+ * Distribution route A (ctxdb0-style): skills ship as package files under
+ * `apps/baas/skills/<skill>/` and `package.json#files` includes `skills`.
+ * We resolve the package root by walking up from this module until we find a
+ * `skills/` directory containing at least one `<skill>/SKILL.md`. This works for
+ * the compiled layout (`dist/skill/assets.js`) and for direct source execution.
+ *
+ * There can be MULTIPLE bundled skills (e.g. `pxbaas-cli`, `pxbaas-app-spec`);
+ * `pxbaas skill install` installs all of them by default.
+ *
+ * NOTE: the standalone single-file binary (`bun build --compile`) does not carry
+ * these files on disk; resolution then fails and callers surface a clear
+ * "requires the npm/source install" error.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Thrown when the bundled skills cannot be located (e.g. single-binary mode). */
+export class SkillAssetsNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SkillAssetsNotFoundError';
+    }
+}
+function moduleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+function isSkillsRoot(dir) {
+    return existsSync(join(dir, 'skills')) && existsSync(join(dir, 'package.json'));
+}
+/** Walk up from the current module to find the app package root (holds `skills/`). */
+export function resolvePackageRoot(startDir = moduleDir()) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        if (isSkillsRoot(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Absolute path to the bundled `skills/` directory. */
+export function resolveSkillsRoot(startDir = moduleDir()) {
+    const root = resolvePackageRoot(startDir);
+    if (!root) {
+        throw new SkillAssetsNotFoundError('Bundled skills not found. `pxbaas skill install` requires the npm or source install (the standalone single-file binary does not bundle skill assets).');
+    }
+    return join(root, 'skills');
+}
+/** Names of all bundled skills under a given `skills/` root (subdirs with a SKILL.md). */
+export async function listBundledSkillsIn(skillsRoot) {
+    const entries = await readdir(skillsRoot, { withFileTypes: true });
+    const names = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith('.'))
+            continue;
+        if (existsSync(join(skillsRoot, e.name, 'SKILL.md')))
+            names.push(e.name);
+    }
+    return names.sort();
+}
+/** Names of all bundled skills (subdirs of the resolved `skills/` that contain a SKILL.md). */
+export async function listBundledSkills(startDir = moduleDir()) {
+    return listBundledSkillsIn(resolveSkillsRoot(startDir));
+}
+/** Absolute path to one bundled skill directory. */
+export function resolveSkillAssetDir(skillName, startDir = moduleDir()) {
+    return join(resolveSkillsRoot(startDir), skillName);
+}
+/** Read the CLI version from the resolved package.json (best-effort). */
+export async function readCliVersion(startDir = moduleDir()) {
+    const root = resolvePackageRoot(startDir);
+    if (!root)
+        return 'unknown';
+    try {
+        const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Recursively list a skill's files as POSIX-style relative paths (e.g. `SKILL.md`,
+ * `references/db-and-meta.md`). Skips hidden files/dirs and `node_modules`.
+ */
+export async function listSkillFiles(assetDir) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                out.push(relative(assetDir, full).split(sep).join('/'));
+            }
+        }
+    }
+    await walk(assetDir);
+    return out.sort();
+}
+//# sourceMappingURL=assets.js.map

package/dist/skill/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/skill/assets.ts"],"names":[],"mappings":"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"}

package/dist/skill/hint.d.ts

@@ -0,0 +1,39 @@
+/**
+ * First-run skill hint (option A).
+ *
+ * Nudges the user once — on any `pxbaas` command — that a bundled Agent Skill can
+ * be installed into a detected Agent host, so they discover `pxbaas skill install`
+ * without us silently writing into their agent config on npm install.
+ *
+ * Deliberately non-intrusive:
+ * - prints to **stderr** (never pollutes `--json` stdout that agents parse)
+ * - skipped when `--json`, when running any `skill` subcommand, when no host is
+ *   detected, when the skill is already installed in a detected host, when the
+ *   hint was shown before (state under ~/.baas), or when BAAS_NO_SKILL_HINT is set
+ * - never throws: a hint failure must not break the actual command
+ */
+export interface SkillHintOptions {
+    /** Global --json flag; when true the hint is suppressed. */
+    json?: boolean;
+    /** $HOME override (defaults to os.homedir()). Injectable for tests. */
+    homeDir?: string;
+    /** Invoked command path, e.g. "db query" or "skill install". */
+    commandPath?: string;
+    /** Environment override (defaults to process.env). Injectable for tests. */
+    env?: NodeJS.ProcessEnv;
+    /** stderr writer override. Injectable for tests. */
+    stderr?: (line: string) => void;
+}
+/**
+ * Print the one-time skill hint when appropriate. Safe to call before any
+ * command action; resolves without side effects when suppressed.
+ */
+export declare function maybePrintSkillHint(options?: SkillHintOptions): Promise<void>;
+/**
+ * First-run hint shown when NO profile is configured yet: point the user to
+ * `pxbaas provision` (free 15-day Zero instance) or `pxbaas login` (own instance).
+ * Non-intrusive: stderr, once, skipped under --json / on onboarding commands /
+ * when a profile already exists / when BAAS_NO_PROVISION_HINT is set.
+ */
+export declare function maybePrintProvisionHint(options?: SkillHintOptions): Promise<void>;
+//# sourceMappingURL=hint.d.ts.map

package/dist/skill/hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint.d.ts","sourceRoot":"","sources":["../../src/skill/hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAQD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvF;AAKD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC3F"}

package/dist/skill/hint.js

@@ -0,0 +1,109 @@
+/**
+ * First-run skill hint (option A).
+ *
+ * Nudges the user once — on any `pxbaas` command — that a bundled Agent Skill can
+ * be installed into a detected Agent host, so they discover `pxbaas skill install`
+ * without us silently writing into their agent config on npm install.
+ *
+ * Deliberately non-intrusive:
+ * - prints to **stderr** (never pollutes `--json` stdout that agents parse)
+ * - skipped when `--json`, when running any `skill` subcommand, when no host is
+ *   detected, when the skill is already installed in a detected host, when the
+ *   hint was shown before (state under ~/.baas), or when BAAS_NO_SKILL_HINT is set
+ * - never throws: a hint failure must not break the actual command
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { detectInstalledHosts, hostSkillDir } from './hosts.js';
+import { classifyTarget } from './ownership.js';
+import { ProfileManager } from '../credentials/profile.js';
+const STATE_RELPATH = join('.baas', 'skill-hint.json');
+function truthy(value) {
+    return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
+}
+/**
+ * Print the one-time skill hint when appropriate. Safe to call before any
+ * command action; resolves without side effects when suppressed.
+ */
+export async function maybePrintSkillHint(options = {}) {
+    const env = options.env ?? process.env;
+    const home = options.homeDir ?? homedir();
+    const write = options.stderr ?? ((line) => process.stderr.write(line + '\n'));
+    // Suppress in machine-readable mode and when explicitly disabled.
+    if (options.json)
+        return;
+    if (truthy(env.BAAS_NO_SKILL_HINT))
+        return;
+    // Do not hint while the user is already running `pxbaas skill ...`.
+    const root = (options.commandPath ?? '').trim().split(/\s+/)[0];
+    if (root === 'skill')
+        return;
+    // Only relevant when at least one supported Agent host directory exists.
+    const hosts = detectInstalledHosts(home);
+    if (hosts.length === 0)
+        return;
+    // Stay quiet if the skill is already installed in any detected host.
+    for (const host of hosts) {
+        if ((await classifyTarget(hostSkillDir(host, home))) === 'owned')
+            return;
+    }
+    // First-run only: skip if we already showed the hint.
+    const stateFile = join(home, STATE_RELPATH);
+    if (existsSync(stateFile))
+        return;
+    write(`Tip: enable the baas AI-agent skill for detected host(s): ${hosts.join(', ')}.`);
+    write(`     Run: pxbaas skill install --host ${hosts[0]}   (or --all). Set BAAS_NO_SKILL_HINT=1 to silence.`);
+    // Record that we showed it (best-effort; never fail the command).
+    try {
+        await mkdir(dirname(stateFile), { mode: 0o700, recursive: true });
+        await writeFile(stateFile, JSON.stringify({ shown: true, at: new Date().toISOString(), hosts }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // ignore — the hint is cosmetic
+    }
+}
+const PROVISION_STATE_RELPATH = join('.baas', 'provision-hint.json');
+const PROVISION_SKIP_ROOTS = new Set(['provision', 'instance', 'login', 'logout', 'profile']);
+/**
+ * First-run hint shown when NO profile is configured yet: point the user to
+ * `pxbaas provision` (free 15-day Zero instance) or `pxbaas login` (own instance).
+ * Non-intrusive: stderr, once, skipped under --json / on onboarding commands /
+ * when a profile already exists / when BAAS_NO_PROVISION_HINT is set.
+ */
+export async function maybePrintProvisionHint(options = {}) {
+    const env = options.env ?? process.env;
+    const home = options.homeDir ?? homedir();
+    const write = options.stderr ?? ((line) => process.stderr.write(line + '\n'));
+    if (options.json)
+        return;
+    if (truthy(env.BAAS_NO_PROVISION_HINT) || truthy(env.BAAS_NO_SKILL_HINT))
+        return;
+    const root = (options.commandPath ?? '').trim().split(/\s+/)[0];
+    if (PROVISION_SKIP_ROOTS.has(root))
+        return;
+    // Skip when a profile is already configured.
+    try {
+        const current = await new ProfileManager(join(home, '.baas')).getCurrentProfile();
+        if (current)
+            return;
+    }
+    catch {
+        return; // profile lookup failed — stay quiet
+    }
+    const stateFile = join(home, PROVISION_STATE_RELPATH);
+    if (existsSync(stateFile))
+        return;
+    write('Tip: no BaaS instance configured yet.');
+    write('     Run: pxbaas provision   (claim a free 15-day PolarDB-X Zero instance)');
+    write('     or:  pxbaas login       (use your own instance).  Set BAAS_NO_PROVISION_HINT=1 to silence.');
+    try {
+        await mkdir(dirname(stateFile), { mode: 0o700, recursive: true });
+        await writeFile(stateFile, JSON.stringify({ shown: true, at: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // ignore — the hint is cosmetic
+    }
+}
+//# sourceMappingURL=hint.js.map

package/dist/skill/hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint.js","sourceRoot":"","sources":["../../src/skill/hint.ts"],"names":[],"mappings":"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"}

package/dist/skill/hosts.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Skill host mapping & detection.
+ *
+ * Mirrors the ctxdb0 `#skillTarget` convention: each supported Agent host keeps
+ * its skills under `~/.<host>/skills/<skill>/`. User-level hosts are verified
+ * against vendor docs; unverified locations are NOT hardcoded here.
+ *
+ * Two install scopes exist:
+ *  - `user` (default): the per-host directory under $HOME.
+ *  - `project`: the repository-level convention (e.g. `.agents/skills`), so the
+ *    skills travel with the code and cloud agents cloning the repo pick them up.
+ *
+ * The vendor-neutral key `agents` maps to `~/.agents/skills` / `.agents/skills`,
+ * which Codex scans and Copilot reads. It is intentionally excluded from `--all`
+ * (install it explicitly) to avoid duplicate copies next to per-host installs.
+ */
+export type HostName = 'qoder' | 'claude' | 'cursor' | 'qwen' | 'hermes' | 'codex' | 'gemini' | 'copilot' | 'qwenworkcn' | 'agents';
+/** Hosts supported by `pxbaas skill install --scope user`. */
+export declare const SUPPORTED_HOSTS: HostName[];
+/** Neutral locations: never installed by `--all`, only by explicit `--host`. */
+export declare const ALL_EXCLUDED_HOSTS: HostName[];
+/**
+ * Host keys accepted for `--scope project`. Some (trae/codebuddy/cline) publish
+ * only a repository-level convention, so they are project-scope only.
+ * Every path below is taken from vendor documentation; do not add guesses.
+ */
+export type ProjectHost = 'claude' | 'qwen' | 'codex' | 'agents' | 'gemini' | 'copilot' | 'trae' | 'codebuddy' | 'cline';
+export declare const PROJECT_HOSTS: ProjectHost[];
+/** Repository-relative skills directory per project-scope host. */
+export declare const PROJECT_SKILL_DIR: Record<ProjectHost, string>;
+export declare function isHostName(value: string): value is HostName;
+export declare function isProjectHost(value: string): value is ProjectHost;
+/** `~/.<host>/skills` root for a user-scope host. */
+export declare function hostSkillsRoot(host: HostName, homeDir: string): string;
+/** Full target directory for a skill under a user-scope host. */
+export declare function hostSkillDir(host: HostName, homeDir: string, skillName?: string): string;
+/** Repository-level skills root for a project-scope host. */
+export declare function projectSkillsRoot(host: ProjectHost, projectRoot: string): string;
+/**
+ * Detect which supported hosts already have a `~/.<host>` directory, i.e. hosts
+ * the user plausibly uses. Used for auto-selection and `--all` (which further
+ * excludes ALL_EXCLUDED_HOSTS at the caller).
+ */
+export declare function detectInstalledHosts(homeDir: string): HostName[];
+//# sourceMappingURL=hosts.d.ts.map

package/dist/skill/hosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../../src/skill/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,QAAQ,CAAC;AAEb,8DAA8D;AAC9D,eAAO,MAAM,eAAe,EAAE,QAAQ,EAWrC,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,EAAE,QAAQ,EAAe,CAAC;AAgBzD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,WAAW,GACX,OAAO,CAAC;AAEZ,eAAO,MAAM,aAAa,EAAE,WAAW,EAUtC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAUzD,CAAC;AAEF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAe,GAAG,MAAM,CAE9F;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEhE"}

package/dist/skill/hosts.js

@@ -0,0 +1,96 @@
+/**
+ * Skill host mapping & detection.
+ *
+ * Mirrors the ctxdb0 `#skillTarget` convention: each supported Agent host keeps
+ * its skills under `~/.<host>/skills/<skill>/`. User-level hosts are verified
+ * against vendor docs; unverified locations are NOT hardcoded here.
+ *
+ * Two install scopes exist:
+ *  - `user` (default): the per-host directory under $HOME.
+ *  - `project`: the repository-level convention (e.g. `.agents/skills`), so the
+ *    skills travel with the code and cloud agents cloning the repo pick them up.
+ *
+ * The vendor-neutral key `agents` maps to `~/.agents/skills` / `.agents/skills`,
+ * which Codex scans and Copilot reads. It is intentionally excluded from `--all`
+ * (install it explicitly) to avoid duplicate copies next to per-host installs.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Hosts supported by `pxbaas skill install --scope user`. */
+export const SUPPORTED_HOSTS = [
+    'qoder',
+    'claude',
+    'cursor',
+    'qwen',
+    'hermes',
+    'codex',
+    'gemini',
+    'copilot',
+    'qwenworkcn',
+    'agents',
+];
+/** Neutral locations: never installed by `--all`, only by explicit `--host`. */
+export const ALL_EXCLUDED_HOSTS = ['agents'];
+/** Host name -> the dot-directory under $HOME that hosts its config/skills. */
+const HOST_DIR = {
+    qoder: '.qoder',
+    claude: '.claude',
+    cursor: '.cursor',
+    qwen: '.qwen',
+    hermes: '.hermes',
+    codex: '.codex',
+    gemini: '.gemini',
+    copilot: '.copilot',
+    qwenworkcn: '.qwenworkcn',
+    agents: '.agents',
+};
+export const PROJECT_HOSTS = [
+    'claude',
+    'qwen',
+    'codex',
+    'agents',
+    'gemini',
+    'copilot',
+    'trae',
+    'codebuddy',
+    'cline',
+];
+/** Repository-relative skills directory per project-scope host. */
+export const PROJECT_SKILL_DIR = {
+    claude: '.claude/skills',
+    qwen: '.qwen/skills',
+    codex: '.agents/skills',
+    agents: '.agents/skills',
+    gemini: '.gemini/skills',
+    copilot: '.github/skills',
+    trae: '.trae/skills',
+    codebuddy: '.codebuddy/skills',
+    cline: '.cline/skills',
+};
+export function isHostName(value) {
+    return SUPPORTED_HOSTS.includes(value);
+}
+export function isProjectHost(value) {
+    return PROJECT_HOSTS.includes(value);
+}
+/** `~/.<host>/skills` root for a user-scope host. */
+export function hostSkillsRoot(host, homeDir) {
+    return join(homeDir, HOST_DIR[host], 'skills');
+}
+/** Full target directory for a skill under a user-scope host. */
+export function hostSkillDir(host, homeDir, skillName = 'pxbaas-cli') {
+    return join(hostSkillsRoot(host, homeDir), skillName);
+}
+/** Repository-level skills root for a project-scope host. */
+export function projectSkillsRoot(host, projectRoot) {
+    return join(projectRoot, PROJECT_SKILL_DIR[host]);
+}
+/**
+ * Detect which supported hosts already have a `~/.<host>` directory, i.e. hosts
+ * the user plausibly uses. Used for auto-selection and `--all` (which further
+ * excludes ALL_EXCLUDED_HOSTS at the caller).
+ */
+export function detectInstalledHosts(homeDir) {
+    return SUPPORTED_HOSTS.filter((host) => existsSync(join(homeDir, HOST_DIR[host])));
+}
+//# sourceMappingURL=hosts.js.map

package/dist/skill/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../../src/skill/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAcjC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAe;IACzC,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,SAAS;IACT,YAAY;IACZ,QAAQ;CACT,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAe,CAAC,QAAQ,CAAC,CAAC;AAEzD,+EAA+E;AAC/E,MAAM,QAAQ,GAA6B;IACzC,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,aAAa;IACzB,MAAM,EAAE,SAAS;CAClB,CAAC;AAkBF,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,QAAQ;IACR,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;IACN,WAAW;IACX,OAAO;CACR,CAAC;AAEF,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,MAAM,EAAE,gBAAgB;IACxB,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,gBAAgB;IACxB,MAAM,EAAE,gBAAgB;IACxB,OAAO,EAAE,gBAAgB;IACzB,IAAI,EAAE,cAAc;IACpB,SAAS,EAAE,mBAAmB;IAC9B,KAAK,EAAE,eAAe;CACvB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAQ,eAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAQ,aAA0B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,OAAe;IAC5D,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,OAAe,EAAE,SAAS,GAAG,YAAY;IACpF,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAE,WAAmB;IACtE,OAAO,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/dist/skill/installer.d.ts

@@ -0,0 +1,100 @@
+/**
+ * SkillManager — install/list/remove ALL bundled Agent Skills (e.g. `pxbaas-cli`,
+ * `pxbaas-app-spec`) into supported Agent hosts.
+ *
+ * Purely local and offline: never touches credentials, profiles, or the network,
+ * so agents can run it without `pxbaas login`. `homeDir` and `skillsRoot` are
+ * injectable for testing.
+ *
+ * Layout: each host has a skills root (`~/.<host>/skills`); every bundled skill is
+ * installed into `<skillsRoot>/<skillName>/` with its own fail-closed owner marker.
+ */
+export type InstallScope = 'user' | 'project';
+export type InstallStatus = 'installed' | 'updated' | 'skipped-foreign' | 'dry-run' | 'error';
+export type RemoveStatus = 'removed' | 'not-installed' | 'skipped-foreign' | 'dry-run' | 'error';
+export type ListStatus = 'installed' | 'not-installed' | 'foreign';
+export interface SkillResult {
+    host: string;
+    skill: string;
+    targetDir: string;
+    status: InstallStatus | RemoveStatus | ListStatus;
+    scope?: InstallScope;
+    filesWritten?: string[];
+    skillVersion?: string;
+    installedAt?: string;
+    reason?: string;
+}
+export interface SkillManagerOptions {
+    /** Base home directory (defaults to os.homedir()). Injectable for tests. */
+    homeDir?: string;
+    /** Directory containing all bundled skills (defaults to resolveSkillsRoot()). */
+    skillsRoot?: string;
+    /** CLI version stamped into markers (defaults to readCliVersion()). */
+    cliVersion?: string;
+    /** Repository root for `--scope project` targets (defaults to process.cwd()). */
+    projectRoot?: string;
+}
+export interface InstallOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    /** Restrict to specific skill names (default: all bundled skills). */
+    skills?: string[];
+}
+export interface RemoveOptions {
+    dryRun?: boolean;
+    confirm?: boolean;
+    skills?: string[];
+}
+/** A resolved install/remove target: a host label plus its skills root directory. */
+export interface ResolvedTarget {
+    host: string;
+    destRoot: string;
+    scope: InstallScope;
+}
+export declare class SkillManager {
+    private readonly homeDir;
+    private readonly skillsRoot;
+    private readonly cliVersion;
+    private readonly projectRoot;
+    private skillsCache;
+    constructor(options?: SkillManagerOptions);
+    /** Async factory that resolves the CLI version from package.json. */
+    static create(options?: SkillManagerOptions): Promise<SkillManager>;
+    /** Bundled skill names (memoized). */
+    bundledSkills(): Promise<string[]>;
+    private selectedSkills;
+    /**
+     * Resolve which host skills-roots to act on.
+     * - `--dir` wins (single custom skills-root, host label "custom")
+     * - `--scope project` requires `--host` (a ProjectHost) or `--dir`; `--all` is
+     *   user-scope only because writing every vendor repo directory is spammy
+     * - `--all` (user scope) → every detected host except ALL_EXCLUDED_HOSTS
+     * - `--host <h>` → that host
+     * - none → auto-detect: exactly one detected host is used; 0 or >1 is an error
+     */
+    resolveTargets(opts: {
+        host?: string;
+        all?: boolean;
+        dir?: string;
+        scope?: InstallScope;
+    }): ResolvedTarget[];
+    /** Install all (or selected) bundled skills into each target's skills root. */
+    install(targets: ResolvedTarget[], options?: InstallOptions): Promise<SkillResult[]>;
+    private installOne;
+    /** Report install state of every bundled skill across all detected hosts. */
+    list(options?: {
+        skills?: string[];
+    }): Promise<SkillResult[]>;
+    /** Report install state of bundled skills in repository-level directories. */
+    listProject(options?: {
+        skills?: string[];
+    }): Promise<SkillResult[]>;
+    private listOne;
+    /**
+     * Remove bundled skills from each target. Only removes directories owned by
+     * pxbaas-cli. Two-phase: without `confirm` (or with `dryRun`) it only previews.
+     */
+    remove(targets: ResolvedTarget[], options?: RemoveOptions): Promise<SkillResult[]>;
+    private removeOne;
+}
+//# sourceMappingURL=installer.d.ts.map