@ory/argus 0.1.0

package/dist/setup.d.ts

@@ -0,0 +1,118 @@
+export interface SetupArgs {
+    projectDir: string;
+    global: boolean;
+    print: boolean;
+    uninstall: boolean;
+}
+export interface HookCommand {
+    type: string;
+    command: string;
+}
+export interface MatcherEntry {
+    matcher: string;
+    hooks: HookCommand[];
+}
+/**
+ * Parse standard setup CLI arguments from process.argv.
+ */
+export declare function parseSetupArgs(opts?: {
+    supportsGlobal?: boolean;
+}): SetupArgs;
+/**
+ * Read and parse a JSON file. Returns empty object if file doesn't exist or is invalid.
+ */
+export declare function readJsonFile(filePath: string): Record<string, unknown>;
+/**
+ * Write a JSON file, creating parent directories if needed.
+ */
+export declare function writeJsonFile(filePath: string, data: unknown): void;
+/**
+ * Check if a hook command belongs to an Ory plugin.
+ */
+export declare function isOryHookCommand(h: HookCommand, binName: string): boolean;
+/**
+ * Resolve the hook command string for a plugin.
+ * Tries require.resolve first, falls back to the global bin name.
+ */
+export declare function resolveHookCommand(packageName: string, binName: string): string;
+/**
+ * Build a matcher-based hook entry: `[{ matcher: "", hooks: [{ type: "command", command }] }]`
+ */
+export declare function matcherHookEntry(cmd: string): MatcherEntry[];
+/**
+ * Merge matcher-based hooks into existing settings, replacing any existing Ory entries.
+ */
+export declare function mergeMatcherHooks(existing: Record<string, unknown>, newHooks: Record<string, MatcherEntry[]>, binName: string): Record<string, unknown>;
+/**
+ * Remove all Ory matcher-based hooks from existing settings.
+ */
+export declare function removeMatcherHooks(existing: Record<string, unknown>, binName: string): Record<string, unknown>;
+/**
+ * Build a flat hook entry: `[{ type: "command", command }]`
+ */
+export declare function flatHookEntry(cmd: string): HookCommand[];
+/**
+ * Merge flat hooks into existing config, replacing any existing Ory entries.
+ */
+export declare function mergeFlatHooks(existing: Record<string, unknown>, newHooks: Record<string, HookCommand[]>, binName: string): Record<string, unknown>;
+/**
+ * Remove all Ory flat hooks from existing config.
+ */
+export declare function removeFlatHooks(existing: Record<string, unknown>, binName: string): Record<string, unknown>;
+/**
+ * Resolve the command + args needed to run the Ory MCP server.
+ * Tries require.resolve first, falls back to the global bin name.
+ */
+export declare function resolveMcpServerCommand(): {
+    command: string;
+    args: string[];
+};
+/**
+ * Generate the mcpServers config object for the Ory MCP server.
+ */
+export declare function mcpServerEntry(cmd?: {
+    command: string;
+    args: string[];
+}): Record<string, unknown>;
+/**
+ * Merge the Ory MCP server into an existing settings object's `mcpServers` key.
+ * Pass an optional `cmd` to override the default resolution (useful when the
+ * caller can resolve the mcp-server entry point more reliably than core can).
+ */
+export declare function mergeMcpServer(existing: Record<string, unknown>, cmd?: {
+    command: string;
+    args: string[];
+}): Record<string, unknown>;
+/**
+ * Remove the Ory MCP server from an existing settings object's `mcpServers` key.
+ */
+export declare function removeMcpServer(existing: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Register a plugin in the Claude Code plugins registry.
+ */
+export declare function registerPlugin(opts: {
+    name: string;
+    installPath: string;
+    version: string;
+    scope: "project" | "user";
+    projectPath?: string;
+}): void;
+/**
+ * Unregister a plugin from the Claude Code plugins registry.
+ */
+export declare function unregisterPlugin(opts: {
+    name: string;
+    scope: "project" | "user";
+    projectPath?: string;
+}): void;
+/**
+ * Print the standard setup help text showing supported environment variables.
+ */
+export declare function printSetupHelp(binName: string, harnessName: string, opts?: {
+    supportsGlobal?: boolean;
+    globalPath?: string;
+}): void;
+/**
+ * Print the "Next steps" text after successful setup.
+ */
+export declare function printNextSteps(harnessName: string, uninstallCmd: string): void;

package/dist/setup.js

@@ -0,0 +1,398 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSetupArgs = parseSetupArgs;
+exports.readJsonFile = readJsonFile;
+exports.writeJsonFile = writeJsonFile;
+exports.isOryHookCommand = isOryHookCommand;
+exports.resolveHookCommand = resolveHookCommand;
+exports.matcherHookEntry = matcherHookEntry;
+exports.mergeMatcherHooks = mergeMatcherHooks;
+exports.removeMatcherHooks = removeMatcherHooks;
+exports.flatHookEntry = flatHookEntry;
+exports.mergeFlatHooks = mergeFlatHooks;
+exports.removeFlatHooks = removeFlatHooks;
+exports.resolveMcpServerCommand = resolveMcpServerCommand;
+exports.mcpServerEntry = mcpServerEntry;
+exports.mergeMcpServer = mergeMcpServer;
+exports.removeMcpServer = removeMcpServer;
+exports.registerPlugin = registerPlugin;
+exports.unregisterPlugin = unregisterPlugin;
+exports.printSetupHelp = printSetupHelp;
+exports.printNextSteps = printNextSteps;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// ─── Arg Parsing ───────────────────────────────────────────────────
+/**
+ * Parse standard setup CLI arguments from process.argv.
+ */
+function parseSetupArgs(opts) {
+    const args = process.argv.slice(2);
+    const result = {
+        projectDir: process.cwd(),
+        global: false,
+        print: false,
+        uninstall: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--project-dir":
+                result.projectDir = args[++i];
+                break;
+            case "--global":
+                if (opts?.supportsGlobal)
+                    result.global = true;
+                break;
+            case "--print":
+                result.print = true;
+                break;
+            case "--uninstall":
+                result.uninstall = true;
+                break;
+        }
+    }
+    return result;
+}
+// ─── JSON File I/O ─────────────────────────────────────────────────
+/**
+ * Read and parse a JSON file. Returns empty object if file doesn't exist or is invalid.
+ */
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write a JSON file, creating parent directories if needed.
+ */
+function writeJsonFile(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+// ─── Hook Command Utilities ────────────────────────────────────────
+/**
+ * Check if a hook command belongs to an Ory plugin.
+ */
+function isOryHookCommand(h, binName) {
+    return h.command?.includes(binName) || h.command?.includes("ory-agent-plugins");
+}
+/**
+ * Resolve the hook command string for a plugin.
+ * Tries require.resolve first, falls back to the global bin name.
+ */
+function resolveHookCommand(packageName, binName) {
+    try {
+        const binPath = require.resolve(packageName);
+        // The package root resolves to the main entry (dist/index.js).
+        // The hook script lives alongside it as dist/hook.js.
+        const hookPath = path.resolve(path.dirname(binPath), "hook.js");
+        return `node ${hookPath}`;
+    }
+    catch {
+        return binName;
+    }
+}
+// ─── Matcher-Based Hooks (Claude Code, Gemini CLI) ─────────────────
+/**
+ * Build a matcher-based hook entry: `[{ matcher: "", hooks: [{ type: "command", command }] }]`
+ */
+function matcherHookEntry(cmd) {
+    return [{ matcher: "", hooks: [{ type: "command", command: cmd }] }];
+}
+/**
+ * Merge matcher-based hooks into existing settings, replacing any existing Ory entries.
+ */
+function mergeMatcherHooks(existing, newHooks, binName) {
+    const merged = { ...existing };
+    const existingHooks = (merged.hooks ?? {});
+    for (const [event, entries] of Object.entries(newHooks)) {
+        const eventEntries = existingHooks[event] ?? [];
+        const filtered = eventEntries.filter((entry) => !entry.hooks?.some((h) => isOryHookCommand(h, binName)));
+        filtered.push(...entries);
+        existingHooks[event] = filtered;
+    }
+    merged.hooks = existingHooks;
+    return merged;
+}
+/**
+ * Remove all Ory matcher-based hooks from existing settings.
+ */
+function removeMatcherHooks(existing, binName) {
+    const merged = { ...existing };
+    const hooks = (merged.hooks ?? {});
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = hooks[event].filter((entry) => !entry.hooks?.some((h) => isOryHookCommand(h, binName)));
+        if (hooks[event].length === 0) {
+            delete hooks[event];
+        }
+    }
+    if (Object.keys(hooks).length === 0) {
+        delete merged.hooks;
+    }
+    else {
+        merged.hooks = hooks;
+    }
+    return merged;
+}
+// ─── Flat Hooks (Codex) ────────────────────────────────────────────
+/**
+ * Build a flat hook entry: `[{ type: "command", command }]`
+ */
+function flatHookEntry(cmd) {
+    return [{ type: "command", command: cmd }];
+}
+/**
+ * Merge flat hooks into existing config, replacing any existing Ory entries.
+ */
+function mergeFlatHooks(existing, newHooks, binName) {
+    const merged = { ...existing };
+    const existingHooks = (merged.hooks ?? {});
+    for (const [event, entries] of Object.entries(newHooks)) {
+        const eventEntries = existingHooks[event] ?? [];
+        const filtered = eventEntries.filter((entry) => !isOryHookCommand(entry, binName));
+        filtered.push(...entries);
+        existingHooks[event] = filtered;
+    }
+    merged.hooks = existingHooks;
+    return merged;
+}
+/**
+ * Remove all Ory flat hooks from existing config.
+ */
+function removeFlatHooks(existing, binName) {
+    const merged = { ...existing };
+    const hooks = (merged.hooks ?? {});
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = hooks[event].filter((entry) => !isOryHookCommand(entry, binName));
+        if (hooks[event].length === 0) {
+            delete hooks[event];
+        }
+    }
+    if (Object.keys(hooks).length === 0) {
+        delete merged.hooks;
+    }
+    else {
+        merged.hooks = hooks;
+    }
+    return merged;
+}
+// ─── MCP Server Config ────────────────────────────────────────────
+const MCP_SERVER_NAME = "ory";
+const MCP_SERVER_PACKAGE = "@ory/mcp-server";
+/**
+ * Resolve the command + args needed to run the Ory MCP server.
+ * Tries require.resolve first, falls back to the global bin name.
+ */
+function resolveMcpServerCommand() {
+    try {
+        const entryPoint = require.resolve(MCP_SERVER_PACKAGE);
+        return { command: "node", args: [entryPoint] };
+    }
+    catch {
+        return { command: "ory-mcp-server", args: [] };
+    }
+}
+/**
+ * Generate the mcpServers config object for the Ory MCP server.
+ */
+function mcpServerEntry(cmd) {
+    const resolved = cmd ?? resolveMcpServerCommand();
+    return {
+        command: resolved.command,
+        ...(resolved.args.length > 0 ? { args: resolved.args } : {}),
+    };
+}
+/**
+ * Merge the Ory MCP server into an existing settings object's `mcpServers` key.
+ * Pass an optional `cmd` to override the default resolution (useful when the
+ * caller can resolve the mcp-server entry point more reliably than core can).
+ */
+function mergeMcpServer(existing, cmd) {
+    const merged = { ...existing };
+    const servers = (merged.mcpServers ?? {});
+    servers[MCP_SERVER_NAME] = mcpServerEntry(cmd);
+    merged.mcpServers = servers;
+    return merged;
+}
+/**
+ * Remove the Ory MCP server from an existing settings object's `mcpServers` key.
+ */
+function removeMcpServer(existing) {
+    const merged = { ...existing };
+    const servers = (merged.mcpServers ?? {});
+    delete servers[MCP_SERVER_NAME];
+    if (Object.keys(servers).length === 0) {
+        delete merged.mcpServers;
+    }
+    else {
+        merged.mcpServers = servers;
+    }
+    return merged;
+}
+/**
+ * Get the path to the Claude Code plugins registry file.
+ */
+function getPluginsRegistryPath() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
+    return path.join(home, ".claude", "plugins", "installed_plugins.json");
+}
+/**
+ * Read the Claude Code plugins registry.
+ */
+function readPluginsRegistry() {
+    const registryPath = getPluginsRegistryPath();
+    if (!fs.existsSync(registryPath)) {
+        return { version: 2, plugins: {} };
+    }
+    try {
+        const data = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
+        return { version: data.version ?? 2, plugins: data.plugins ?? {} };
+    }
+    catch {
+        return { version: 2, plugins: {} };
+    }
+}
+/**
+ * Write the Claude Code plugins registry.
+ */
+function writePluginsRegistry(registry) {
+    const registryPath = getPluginsRegistryPath();
+    const dir = path.dirname(registryPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n");
+}
+/**
+ * Register a plugin in the Claude Code plugins registry.
+ */
+function registerPlugin(opts) {
+    const registry = readPluginsRegistry();
+    const key = `${opts.name}@inline`;
+    const now = new Date().toISOString();
+    const entry = {
+        scope: opts.scope,
+        installPath: opts.installPath,
+        version: opts.version,
+        installedAt: now,
+        lastUpdated: now,
+    };
+    if (opts.projectPath) {
+        entry.projectPath = opts.projectPath;
+    }
+    // Replace existing entry for the same scope/project, or add new
+    const existing = registry.plugins[key] ?? [];
+    const filtered = existing.filter((e) => {
+        if (opts.scope === "user")
+            return e.scope !== "user";
+        return !(e.scope === "project" && e.projectPath === opts.projectPath);
+    });
+    filtered.push(entry);
+    registry.plugins[key] = filtered;
+    writePluginsRegistry(registry);
+}
+/**
+ * Unregister a plugin from the Claude Code plugins registry.
+ */
+function unregisterPlugin(opts) {
+    const registry = readPluginsRegistry();
+    const key = `${opts.name}@inline`;
+    const existing = registry.plugins[key];
+    if (!existing)
+        return;
+    const filtered = existing.filter((e) => {
+        if (opts.scope === "user")
+            return e.scope !== "user";
+        return !(e.scope === "project" && e.projectPath === opts.projectPath);
+    });
+    if (filtered.length === 0) {
+        delete registry.plugins[key];
+    }
+    else {
+        registry.plugins[key] = filtered;
+    }
+    writePluginsRegistry(registry);
+}
+// ─── Shared Output ─────────────────────────────────────────────────
+/**
+ * Print the standard setup help text showing supported environment variables.
+ */
+function printSetupHelp(binName, harnessName, opts) {
+    console.log(`
+${binName} — Configure Ory hooks for ${harnessName}
+
+Usage:
+  npx ${binName} [options]
+
+Options:
+  --project-dir <path>  Project directory (default: cwd)${opts?.supportsGlobal ? `\n  --global              Install to ${opts.globalPath ?? "global config"} instead of project` : ""}
+  --print               Print generated config to stdout without writing
+  --uninstall           Remove Ory hooks from config
+  -h, --help            Show this help
+
+Environment variables:
+  ORY_PROJECT_URL       Your Ory project URL (required at runtime)
+  ORY_API_KEY           Ory API key (required at runtime)
+  ORY_SESSION_TOKEN     Session token for agent authentication
+  ORY_AGENT_DEBUG       Set to "true" for debug logging
+  ORY_AGENT_LOG_FILE    Path to write debug logs
+  ORY_AGENT_SUBJECT_ID  Override the subject ID for permission checks
+`);
+}
+/**
+ * Print the "Next steps" text after successful setup.
+ */
+function printNextSteps(harnessName, uninstallCmd) {
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Set required environment variables:");
+    console.log("     export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+    console.log("     export ORY_API_KEY=ory_pat_...");
+    console.log("");
+    console.log("  2. Optionally enable debug logging:");
+    console.log("     export ORY_AGENT_DEBUG=true");
+    console.log("");
+    console.log(`  3. Start ${harnessName} in your project directory.`);
+    console.log("");
+    console.log(`To uninstall: ${uninstallCmd}`);
+}

package/dist/skills.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical Ory agent skills and commands.
+ *
+ * The skill playbooks (auth-setup, login-flow, social-login, local-dev) and the
+ * local-stack commands (local-up, local-down) live once, as token-bearing
+ * templates under `packages/core/assets/`. Every harness plugin renders them
+ * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
+ * harness's CLI binary, package name, and the way it references sibling skills
+ * and commands. Plugins then write the rendered docs into whatever location
+ * their harness discovers skills/commands from (a marketplace plugin dir, an
+ * extension bundle, `~/.codex/skills`, `.opencode/skills`, …).
+ *
+ * This keeps the ~1200 lines of guidance in one place — there is no per-harness
+ * copy to drift.
+ */
+/** Names of the skills materialized by the plugins (for uninstall cleanup). */
+export declare const ORY_SKILL_NAMES: readonly string[];
+/** Skill names of the local-stack commands when rendered as skills. */
+export declare const ORY_COMMAND_SKILL_NAMES: readonly string[];
+/** File stems of the local-stack commands when rendered as commands. */
+export declare const ORY_COMMAND_SLUGS: readonly string[];
+export interface RenderedSkill {
+    /** Stable id, e.g. "auth-setup". */
+    id: string;
+    /** Skill name / frontmatter `name`, e.g. "ory-auth-setup". */
+    name: string;
+    /** One-line description (rendered). */
+    description: string;
+    /** Markdown body without frontmatter (rendered). */
+    body: string;
+    /** Full `SKILL.md` content: frontmatter + body (rendered). */
+    markdown: string;
+}
+export interface RenderedCommand {
+    /** Stable id, e.g. "local-up". */
+    id: string;
+    /** Skill-style name, e.g. "ory-local-up". */
+    name: string;
+    /** Command slug / file stem, e.g. "local-up". */
+    slug: string;
+    /** One-line description (rendered). */
+    description: string;
+    /** Markdown body (rendered). */
+    body: string;
+}
+export interface RenderProfileOptions {
+    /** CLI binary the harness exposes, e.g. "ory-codex". */
+    binName: string;
+    /** npm package name, e.g. "@ory/codex". */
+    packageName: string;
+}
+/**
+ * Render the four guide skills for a harness as `SKILL.md` documents.
+ */
+export declare function renderOrySkills(harness: string, opts: RenderProfileOptions): RenderedSkill[];
+/**
+ * Render the two local-stack commands for a harness. The `body` is the rendered
+ * markdown; callers format it into the harness's command shape (plain markdown,
+ * TOML, frontmatter markdown) or wrap it as a skill via {@link commandToSkill}.
+ */
+export declare function renderOryCommands(harness: string, opts: RenderProfileOptions): RenderedCommand[];
+/** Compose a `SKILL.md` from its parts. */
+export declare function toSkillMarkdown(name: string, description: string, body: string): string;
+/** Wrap a rendered command as a user-invocable skill (Codex, OpenClaw). */
+export declare function commandToSkill(cmd: RenderedCommand): RenderedSkill;
+/** Render a command as a Gemini CLI TOML command definition. */
+export declare function commandToToml(cmd: RenderedCommand): string;
+/** Render a command as an OpenCode markdown command (frontmatter + body). */
+export declare function commandToFrontmatterMarkdown(cmd: RenderedCommand): string;
+/** Render a command as a plain markdown command file (Claude Code). */
+export declare function commandToPlainMarkdown(cmd: RenderedCommand): string;
+/**
+ * Write each skill into `<skillsDir>/<name>/SKILL.md`. Overwrites existing
+ * files; creates directories as needed.
+ */
+export declare function writeSkillTree(skillsDir: string, skills: RenderedSkill[]): void;
+/** Remove the named skill directories from `skillsDir` (best-effort). */
+export declare function removeSkillDirs(skillsDir: string, names: readonly string[]): void;