@polardbx/pxbaas 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/instance/zero-whitelist.js

@@ -0,0 +1,67 @@
+/**
+ * Zero whitelist self-service helpers (CLI side).
+ *
+ * The whitelist API authenticates with a Studio-credential HASH (not the pxz_token
+ * ownership cookie) and addresses the instance by its cloud id (`pxsp-*`), so this
+ * module turns a locally-bound Zero record into the (cloudInstanceId, studioHash)
+ * pair the driver needs — and enforces the "Zero instances only" guard.
+ *
+ * The dashboard password and its derived sha256("supabase:"+password) are NEVER
+ * returned in any printable field; only the opaque `studioHash` is handed to the
+ * driver. See references/provision.md and the pxbaas-cli SKILL safety rules.
+ */
+import { createHash } from 'node:crypto';
+import { ZeroDriver } from '@polardbx/pxbaas-client';
+import { ProfileManager } from '../credentials/profile.js';
+import { ZeroStore } from './zero-store.js';
+/**
+ * sha256hex("<user>:<password>"), UTF-8, no trailing newline. Equivalent to the
+ * password — never log or persist it. `user` is fixed to `supabase` by the API.
+ */
+export function studioCredentialHash(password, user = 'supabase') {
+    return createHash('sha256').update(`${user}:${password}`, 'utf8').digest('hex');
+}
+/**
+ * Resolve which Zero instance a `whitelist get|add` targets.
+ *
+ * - `opts.id` (an `sbx_*` ownership id) selects explicitly.
+ * - Otherwise the current profile is used and MUST be `source === 'zero'`.
+ *
+ * Throws a plain Error (clear, user-facing) when the target is not a locally-bound
+ * Zero instance or has no stored dashboard password — the whitelist surface is
+ * Zero-only by design.
+ */
+export async function resolveWhitelistTarget(opts) {
+    const store = new ZeroStore();
+    let record;
+    if (opts.id) {
+        record = await store.getInstance(opts.id);
+        if (!record) {
+            throw new Error(`No Zero instance '${opts.id}' bound on this machine. Whitelist management is only available for Zero-provisioned instances.`);
+        }
+    }
+    else {
+        const current = await new ProfileManager().getCurrentProfile();
+        if (!current) {
+            throw new Error('No active profile. Run `pxbaas provision` to claim a Zero instance first.');
+        }
+        if (current.source !== 'zero') {
+            throw new Error(`Whitelist management is only available for Zero-provisioned instances; current profile '${current.name}' is not a Zero instance (source='${current.source ?? 'login'}').`);
+        }
+        record =
+            (current.zeroInstanceId ? await store.getInstance(current.zeroInstanceId) : null) ??
+                (await store.findInstanceByProfile(current.name));
+        if (!record) {
+            throw new Error(`Zero instance for profile '${current.name}' is not bound locally; cannot authenticate the whitelist API.`);
+        }
+    }
+    if (!record.dashboardPassword) {
+        throw new Error('This Zero instance has no stored dashboard password, so the whitelist API cannot be authenticated. Re-provision from this machine (`pxbaas provision`).');
+    }
+    return {
+        record,
+        cloudInstanceId: ZeroDriver.cloudInstanceId(record.endpoint),
+        studioHash: studioCredentialHash(record.dashboardPassword),
+    };
+}
+//# sourceMappingURL=zero-whitelist.js.map

package/dist/instance/zero-whitelist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-whitelist.js","sourceRoot":"","sources":["../../src/instance/zero-whitelist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAA2B,MAAM,iBAAiB,CAAC;AAErE;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,IAAI,GAAG,UAAU;IACtE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClF,CAAC;AAUD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAAgC;IAC3E,MAAM,KAAK,GAAG,IAAI,SAAS,EAAE,CAAC;IAC9B,IAAI,MAAiC,CAAC;IAEtC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,EAAE,iGAAiG,CAAC,CAAC;QACjJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,iBAAiB,EAAE,CAAC;QAC/D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,2FAA2F,OAAO,CAAC,IAAI,qCAAqC,OAAO,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC,CAAC;QAC9L,CAAC;QACD,MAAM;YACJ,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBACjF,CAAC,MAAM,KAAK,CAAC,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,IAAI,gEAAgE,CAAC,CAAC;QAC9H,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,yJAAyJ,CAAC,CAAC;IAC7K,CAAC;IAED,OAAO;QACL,MAAM;QACN,eAAe,EAAE,UAAU,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC5D,UAAU,EAAE,oBAAoB,CAAC,MAAM,CAAC,iBAAiB,CAAC;KAC3D,CAAC;AACJ,CAAC"}

package/dist/main.js

@@ -1,15 +1,22 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import { registerCommands } from './cli/root.js';
-import { ProfileManager, setCliProfileOverrideGlobal } from './credentials/profile.js';
+import { TOP_LEVEL_AGENT_GUIDE } from './cli/help-guides.js';
+import { ProfileManager, isProfileCreatingCommand, setCliProfileOverrideGlobal, } from './credentials/profile.js';
+import { resolvePackageVersion } from './version.js';
 // Global options
 program
     .name('pxbaas')
     .description('PolarDB-X BaaS CLI')
-    .version('0.0.0-dev')
+    // Read from package.json at runtime: a hardcoded string here reported
+    // `0.0.0-dev` for every build, so `--version` could never identify a release.
+    .version(resolvePackageVersion())
     .option('--json', 'Output in JSON format')
     .option('--profile <name>', 'Use specific profile')
-    .option('--debug', 'Enable debug output');
+    .option('--debug', 'Enable debug output')
+    // Discoverability for coding agents: the full develop-and-deploy workflow
+    // lives under `pxbaas app --help`; keep this pointer to three lines.
+    .addHelpText('after', TOP_LEVEL_AGENT_GUIDE);
 // Register all commands
 registerCommands(program);
 // `--profile` is a program-level option, so commander only parses it when given
@@ -25,6 +32,15 @@ const declareProfileOption = (cmd) => {
     cmd.commands.forEach(declareProfileOption);
 };
 declareProfileOption(program);
+/** Full command path of the action command (e.g. ['profile','import']), program name excluded. */
+const commandPathOf = (actionCommand) => {
+    const parts = [];
+    for (let c = actionCommand; c && c !== program; c = c.parent) {
+        if (c.name())
+            parts.unshift(c.name());
+    }
+    return parts;
+};
 // Resolve --profile once, before any command runs: validate it exists (fail loudly
 // instead of silently falling back to the current profile) and publish it as a
 // process-wide override. Never persisted — `profile ls` current marker is untouched.
@@ -32,6 +48,13 @@ program.hook('preAction', async (_thisCommand, actionCommand) => {
     const requested = (actionCommand.opts().profile ?? program.opts().profile);
     if (!requested)
         return;
+    // `login` / `profile import` write the named profile, so an unknown name is their
+    // precondition, not an error. Still publish the override: the command must read and
+    // write that exact profile rather than whatever happens to be current.
+    if (isProfileCreatingCommand(commandPathOf(actionCommand))) {
+        setCliProfileOverrideGlobal(requested);
+        return;
+    }
     const manager = new ProfileManager();
     const known = await manager.listProfiles();
     if (!known.some((p) => p.name === requested)) {

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAW,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAEvF,iBAAiB;AACjB,OAAO;KACJ,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CAAC,oBAAoB,CAAC;KACjC,OAAO,CAAC,WAAW,CAAC;KACpB,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;KAClD,MAAM,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;AAE5C,wBAAwB;AACxB,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAE1B,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,sEAAsE;AACtE,mEAAmE;AACnE,MAAM,oBAAoB,GAAG,CAAC,GAAY,EAAQ,EAAE;IAClD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAC;IACzD,CAAC;IACD,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAC7C,CAAC,CAAC;AACF,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,mFAAmF;AACnF,+EAA+E;AAC/E,qFAAqF;AACrF,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE;IAC9D,MAAM,SAAS,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAE5D,CAAC;IACd,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;QAC9D,OAAO,CAAC,KAAK,CACX,uBAAuB,SAAS,0BAA0B,KAAK,EAAE,CAClE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,2BAA2B,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC,CAAC,CAAC;AAEH,kBAAkB;AAClB,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/skill/agents-md.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export declare const AGENTS_MD_FILE = "AGENTS.md";
+export declare const BEGIN_MARKER = "<!-- BEGIN pxbaas-skills (managed by pxbaas skill install; do not edit) -->";
+export declare const END_MARKER = "<!-- END pxbaas-skills -->";
+export declare function renderBlock(lines: string[]): string;
+export declare function upsertAgentsMdBlock(projectRoot: string, lines: string[]): Promise<{
+    path: string;
+    created: boolean;
+}>;
+export declare function removeAgentsMdBlock(projectRoot: string): Promise<{
+    path: string;
+    removed: boolean;
+    deletedFile: boolean;
+}>;
+export declare function agentsMdBlockPresent(projectRoot: string): Promise<boolean>;
+//# sourceMappingURL=agents-md.d.ts.map

package/dist/skill/agents-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../src/skill/agents-md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,eAAO,MAAM,cAAc,cAAc,CAAC;AAC1C,eAAO,MAAM,YAAY,gFACsD,CAAC;AAChF,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAUvD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAa7C;AAED,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAYnE;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhF"}

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/hosts.d.ts

@@ -2,20 +2,44 @@
  * Skill host mapping & detection.
  *
  * Mirrors the ctxdb0 `#skillTarget` convention: each supported Agent host keeps
- * its skills under `~/.<host>/skills/<skill>/`. Codex (plugin marketplace) is
- * intentionally out of scope for M1.
+ * 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';
-/** Hosts supported by `pxbaas skill install` (M1). */
+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;
-/** `~/.<host>/skills` root for a host. */
+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 the pxbaas-cli skill under a host. */
+/** 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`.
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../../src/skill/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzE,sDAAsD;AACtD,eAAO,MAAM,eAAe,EAAE,QAAQ,EAAoD,CAAC;AAW3F,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAe,GAAG,MAAM,CAE9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEhE"}
+{"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

@@ -2,13 +2,35 @@
  * Skill host mapping & detection.
  *
  * Mirrors the ctxdb0 `#skillTarget` convention: each supported Agent host keeps
- * its skills under `~/.<host>/skills/<skill>/`. Codex (plugin marketplace) is
- * intentionally out of scope for M1.
+ * 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` (M1). */
-export const SUPPORTED_HOSTS = ['qoder', 'claude', 'cursor', 'qwen', 'hermes'];
+/** 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',
@@ -16,21 +38,57 @@ const HOST_DIR = {
     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);
 }
-/** `~/.<host>/skills` root for a host. */
+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 the pxbaas-cli skill under a host. */
+/** 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`.
+ * 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])));

package/dist/skill/hosts.js.map

@@ -1 +1 @@
-{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../../src/skill/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,sDAAsD;AACtD,MAAM,CAAC,MAAM,eAAe,GAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE3F,+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;CAClB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAQ,eAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,OAAe;IAC5D,OAAO,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED,mEAAmE;AACnE,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;;;GAGG;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"}
+{"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

@@ -9,7 +9,7 @@
  * Layout: each host has a skills root (`~/.<host>/skills`); every bundled skill is
  * installed into `<skillsRoot>/<skillName>/` with its own fail-closed owner marker.
  */
-import { type HostName } from './hosts.js';
+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';
@@ -18,6 +18,7 @@ export interface SkillResult {
     skill: string;
     targetDir: string;
     status: InstallStatus | RemoveStatus | ListStatus;
+    scope?: InstallScope;
     filesWritten?: string[];
     skillVersion?: string;
     installedAt?: string;
@@ -30,6 +31,8 @@ export interface SkillManagerOptions {
     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;
@@ -46,11 +49,13 @@ export interface RemoveOptions {
 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. */
@@ -61,14 +66,17 @@ export declare class SkillManager {
     /**
      * Resolve which host skills-roots to act on.
      * - `--dir` wins (single custom skills-root, host label "custom")
-     * - `--all` → every detected host (those with an existing ~/.<host>)
+     * - `--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?: HostName;
+        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[]>;
@@ -77,6 +85,10 @@ export declare class SkillManager {
     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

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

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/skill/installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EAAwC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGjF,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC;AAC9F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC;AACjG,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,eAAe,GAAG,SAAS,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,UAAU,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,WAAW,CAAyB;gBAEhC,OAAO,GAAE,mBAAwB;IAM7C,qEAAqE;WACxD,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IAK7E,sCAAsC;IAChC,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAO1B,cAAc;IAU5B;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,EAAE;IA0BxF,+EAA+E;IACzE,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAmBhF,UAAU;IA+DxB,6EAA6E;IACvE,IAAI,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAYzD,OAAO;IAUrB;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAW9E,SAAS;CAgBxB"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/skill/installer.ts"],"names":[],"mappings":"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"}