@ory/argus 0.13.8 → 0.14.0

package/dist/setup-actions.js

@@ -0,0 +1,507 @@
+"use strict";
+/**
+ * Headless setup actions — the prompt-free, presentation-free core of the
+ * install walkthrough, driven by the local web installer's JSON API (and
+ * reusable anywhere the interactive TTY wizard's step *decisions* live outside
+ * the process, e.g. in a browser).
+ *
+ * Each function performs exactly one step of the same flow the TTY wizard in
+ * {@link file://./interactive-setup.ts} runs — sign in, pick / create a
+ * workspace and project, enable DCR, provision the OAuth2 client, grant tool
+ * permissions, provision the project API key — but returns a plain result
+ * object instead of prompting or printing. The heavy lifting (CLI arg shapes,
+ * OPL model inspection/merge, Console-API key minting) is imported from
+ * `interactive-setup.ts` so there is a single source of truth for it; only the
+ * thin, prompt-free orchestration lives here.
+ *
+ * Everything is fail-open: an action never throws for an expected failure
+ * (CLI error, network blip, missing session) — it returns `{ ok: false }` with
+ * a short message the UI can surface.
+ */
+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.PROJECT_CAP = void 0;
+exports.resolveNamespace = resolveNamespace;
+exports.ensureOryCli = ensureOryCli;
+exports.isSignedIn = isSignedIn;
+exports.startSignIn = startSignIn;
+exports.listWorkspaces = listWorkspaces;
+exports.createWorkspace = createWorkspace;
+exports.listProjects = listProjects;
+exports.createProject = createProject;
+exports.resolveProjectUrl = resolveProjectUrl;
+exports.getDcrState = getDcrState;
+exports.enableDcrAction = enableDcrAction;
+exports.ensureManagedLoginUi = ensureManagedLoginUi;
+exports.resolveIdentityName = resolveIdentityName;
+exports.resourceUserLabel = resourceUserLabel;
+exports.provisionOAuth2Client = provisionOAuth2Client;
+exports.saveNetworkConfig = saveNetworkConfig;
+exports.runFullSetup = runFullSetup;
+exports.inspectPermissions = inspectPermissions;
+exports.provisionPermissions = provisionPermissions;
+exports.grantToolPermissions = grantToolPermissions;
+exports.provisionProjectApiKey = provisionProjectApiKey;
+exports.configureAuditOnly = configureAuditOnly;
+exports.setPermissionMode = setPermissionMode;
+exports.configureLocalStack = configureLocalStack;
+const node_child_process_1 = require("node:child_process");
+const interactive_setup_js_1 = require("./interactive-setup.js");
+const project_api_key_js_1 = require("./project-api-key.js");
+const config_js_1 = require("./config.js");
+const branding_js_1 = require("./branding.js");
+const auth_js_1 = require("./auth.js");
+const auth_store_js_1 = require("./auth-store.js");
+const tool_catalog_js_1 = require("./tool-catalog.js");
+const user_login_js_1 = require("./user-login.js");
+const agent_auth_js_1 = require("./agent-auth.js");
+const client_js_1 = require("./client.js");
+const subject_js_1 = require("./subject.js");
+const index_js_1 = require("./local/index.js");
+const os = __importStar(require("node:os"));
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+/**
+ * Ensure the `ory` CLI is available. Probes the default (or injected) runner;
+ * if the binary isn't on `PATH`, installs `@ory/cli` into a plugin-managed dir
+ * and returns a runner bound to it. Never throws.
+ */
+async function ensureOryCli(deps = {}) {
+    const runner = deps.runner ?? (0, interactive_setup_js_1.createOryRunner)("ory");
+    if ((0, interactive_setup_js_1.oryCliPresent)(runner))
+        return { present: true, installed: false, runner };
+    const install = deps.installOryCliFn ?? interactive_setup_js_1.installOryCli;
+    let installed;
+    try {
+        installed = await install();
+    }
+    catch {
+        installed = null;
+    }
+    return { present: !!installed, installed: !!installed, runner: installed };
+}
+// ─── sign in ──────────────────────────────────────────────────────────────
+/** Whether the `ory` CLI already holds a valid Ory Network session. */
+function isSignedIn(runner) {
+    return runner.exec(["list", "workspaces", "--format", "json"]).status === 0;
+}
+/**
+ * Launch the interactive `ory auth` browser sign-in as a detached child so the
+ * HTTP server's event loop stays free (unlike `runner.exec`, which is
+ * spawnSync). The Ory CLI opens its own browser window and runs a local
+ * callback listener; we only watch its exit code. Returns a handle whose
+ * `done` promise resolves when sign-in completes. Requires `runner.bin`.
+ */
+function startSignIn(runner) {
+    const bin = runner.bin;
+    if (!bin) {
+        return { done: Promise.resolve(false), cancel() { } };
+    }
+    const child = (0, node_child_process_1.spawn)(bin, ["auth"], { stdio: "ignore" });
+    const done = new Promise((resolve) => {
+        child.on("exit", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+    return { done, cancel: () => child.kill() };
+}
+// ─── workspaces & projects ──────────────────────────────────────────────────
+function listWorkspaces(runner) {
+    const r = runner.exec(["list", "workspaces", "--format", "json"]);
+    if (r.status !== 0)
+        return null;
+    return (0, interactive_setup_js_1.parseList)(r.stdout, "workspaces");
+}
+function createWorkspace(runner, name) {
+    const r = runner.exec(["create", "workspace", "--name", name, "--format", "json", "--yes"]);
+    if (r.status !== 0)
+        return { ok: false, error: r.stderr.trim() || "unknown error" };
+    const workspace = (0, interactive_setup_js_1.parseObject)(r.stdout);
+    if (!workspace?.id)
+        return { ok: false, error: "created workspace had no id" };
+    return { ok: true, value: workspace };
+}
+function listProjects(runner, workspaceId) {
+    return (0, interactive_setup_js_1.listProjects)(runner, workspaceId);
+}
+function createProject(runner, workspaceId, name) {
+    const r = runner.exec([
+        "create",
+        "project",
+        "--name",
+        name,
+        "--workspace",
+        workspaceId,
+        "--format",
+        "json",
+        "--yes",
+    ]);
+    if (r.status !== 0)
+        return { ok: false, error: r.stderr.trim() || "unknown error" };
+    const project = (0, interactive_setup_js_1.parseObject)(r.stdout);
+    if (!project?.id)
+        return { ok: false, error: "created project had no id" };
+    return { ok: true, value: project };
+}
+/** Ory Network Developer-plan project cap per workspace. */
+exports.PROJECT_CAP = 2;
+/**
+ * Resolve a project's canonical SDK URL from its slug, refusing a missing slug
+ * or one that is actually the project id (a UUID) — either would build a URL
+ * that points nowhere.
+ */
+function resolveProjectUrl(project) {
+    if (!project.slug || (0, config_js_1.looksLikeProjectId)(project.slug)) {
+        return { ok: false, error: "could not resolve the project slug (needed for the SDK URL)" };
+    }
+    try {
+        return { ok: true, value: (0, interactive_setup_js_1.projectUrlFromSlug)(project.slug) };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ─── DCR & OAuth2 client ──────────────────────────────────────────────────
+/** Current DCR state: true/false when known, null when it couldn't be read. */
+function getDcrState(runner, projectId) {
+    return (0, interactive_setup_js_1.dcrEnabled)(runner, projectId);
+}
+/** Enable DCR on the project. Returns true on success. */
+function enableDcrAction(runner, projectId) {
+    return (0, interactive_setup_js_1.enableDcr)(runner, projectId);
+}
+/**
+ * Ensure the project's OAuth2 login/consent UI works for a hosted browser
+ * login. A CLI-created project defaults these to the `localhost:3000`
+ * quickstart sample; this clears them so the Ory Managed Account Experience
+ * renders the login instead. Returns the resulting state so the UI can report
+ * it: `managed` (fixed or already managed), `custom_external` (a deliberate
+ * custom UI, left as-is), or `unknown` (couldn't read the config).
+ */
+function ensureManagedLoginUi(runner, projectId) {
+    const state = (0, interactive_setup_js_1.projectLoginUiState)(runner, projectId);
+    if (state === "loopback") {
+        return (0, interactive_setup_js_1.useManagedAccountExperience)(runner, projectId) ? "managed" : "unknown";
+    }
+    return state;
+}
+/**
+ * Best-effort human-readable name for a signed-in identity, resolved via the
+ * admin `ory` CLI (`ory get identity`). The PKCE login's id_token carries only
+ * an opaque subject id under the default `openid` scope, so rather than show a
+ * UUID we look the identity up by id and read a display trait (email → username
+ * → name). Returns undefined on any CLI/parse failure so callers fall back to
+ * the id.
+ */
+function resolveIdentityName(runner, projectId, subjectId) {
+    const r = runner.exec([
+        "get",
+        "identity",
+        subjectId,
+        "--project",
+        projectId,
+        "--format",
+        "json",
+    ]);
+    if (r.status !== 0)
+        return undefined;
+    const identity = (0, interactive_setup_js_1.parseObject)(r.stdout);
+    return displayNameFromTraits(identity?.traits);
+}
+/** Pull a display name out of a Kratos identity's traits (best-effort). */
+function displayNameFromTraits(traits) {
+    if (!traits || typeof traits !== "object")
+        return undefined;
+    const t = traits;
+    if (typeof t.email === "string" && t.email.trim())
+        return t.email.trim();
+    if (typeof t.username === "string" && t.username.trim())
+        return t.username.trim();
+    const name = t.name;
+    if (typeof name === "string" && name.trim())
+        return name.trim();
+    if (name && typeof name === "object") {
+        const n = name;
+        const parts = [n.first, n.last].filter((x) => typeof x === "string" && x.trim().length > 0);
+        if (parts.length)
+            return parts.join(" ");
+    }
+    return undefined;
+}
+/**
+ * Readable label for a signed-in user when naming a resource (e.g. a project
+ * API key), so a shared project's resource list shows an email/username rather
+ * than an opaque `user:<uuid>`. Looks the identity up via the admin CLI and
+ * falls back to the subject label when no name resolves (no runner, or the
+ * lookup fails). The raw subject id is read from either subject shape.
+ */
+function resourceUserLabel(runner, projectId, subject) {
+    const sid = "subjectId" in subject ? subject.subjectId : subject.subjectSet.object;
+    const name = runner ? resolveIdentityName(runner, projectId, sid) : undefined;
+    return name ?? (0, subject_js_1.subjectLabel)(subject);
+}
+/**
+ * Find or create the public PKCE OAuth2 client the user login needs. Reuses an
+ * existing plugin-provisioned client on the project so a re-run never mints a
+ * duplicate.
+ */
+function provisionOAuth2Client(runner, projectId) {
+    const existing = (0, interactive_setup_js_1.findExistingOAuth2Client)(runner, projectId);
+    if (existing)
+        return { ok: true, clientId: existing, name: branding_js_1.USER_LOGIN_CLIENT_NAME, reused: true };
+    const clientId = (0, interactive_setup_js_1.createOAuth2Client)(runner, projectId);
+    return {
+        ok: !!clientId,
+        clientId: clientId ?? undefined,
+        name: branding_js_1.USER_LOGIN_CLIENT_NAME,
+        reused: false,
+    };
+}
+/** Persist the resolved Ory Network connection and enable the user login. */
+function saveNetworkConfig(input) {
+    (0, config_js_1.saveConfig)({
+        projectUrl: input.projectUrl,
+        projectId: input.projectId,
+        projectName: input.projectName,
+        workspaceName: input.workspaceName,
+        oauth2ClientId: input.oauth2ClientId,
+        auditOnly: false,
+    });
+}
+/**
+ * Run the PKCE user login (opens a browser and awaits the loopback callback)
+ * and resolve the agent DCR identity, so the next session is fully wired.
+ * Best-effort: a declined or failed login just reports `authenticated: false`.
+ *
+ * `target` pins the project the wizard just selected. The login gate resolves
+ * its URL/client id through `resolveConfig()`, which is **env-first** — so a
+ * stale `ORY_PROJECT_URL` / `ORY_SDK_URL` / `ORY_OAUTH2_CLIENT_ID` left in the
+ * user's shell (e.g. `http://localhost:3000` from a local app) would otherwise
+ * override the project they just picked and launch the browser at the wrong
+ * URL. During install the fresh selection is ground truth, so we pin it into
+ * the environment for the login. (The process exits after install, so this
+ * doesn't leak into a long-lived session.)
+ */
+async function runFullSetup(binName, harness, deps = {}, target = {}) {
+    const clientFactory = deps.clientFactory ?? client_js_1.OryAgentClient.fromEnv;
+    const userLogin = deps.userLoginFn ?? user_login_js_1.ensureUserAuthenticated;
+    const agentGate = deps.agentGateFn ?? agent_auth_js_1.ensureAgentIdentity;
+    // Scoped to the login call (restored after) so a stale ORY_PROJECT_URL /
+    // ORY_OAUTH2_CLIENT_ID can't override the selected project, and the override
+    // doesn't leak past the login — later steps address the project by id.
+    const prevUrl = process.env.ORY_PROJECT_URL;
+    const prevClient = process.env.ORY_OAUTH2_CLIENT_ID;
+    if (target.projectUrl)
+        process.env.ORY_PROJECT_URL = target.projectUrl;
+    if (target.oauth2ClientId)
+        process.env.ORY_OAUTH2_CLIENT_ID = target.oauth2ClientId;
+    try {
+        const client = clientFactory(harness);
+        const decision = await userLogin(client, { binName, harness });
+        await agentGate(client, { harness });
+        const authenticated = decision.proceed && !!decision.subject;
+        const subject = authenticated ? (0, subject_js_1.resolveUserSubject)(client) : null;
+        const usable = subject && (0, subject_js_1.subjectLabel)(subject) !== "agent:unknown" ? subject : null;
+        // Prefer a human-readable name (email/name) from the login's id_token over
+        // the opaque subject id, so the UI shows who signed in rather than a UUID.
+        const displayName = usable ? (0, auth_js_1.displayNameFromIdToken)((0, auth_store_js_1.loadTokens)()?.idToken) : undefined;
+        return {
+            authenticated,
+            subject: usable,
+            subjectLabel: usable ? (displayName ?? (0, subject_js_1.subjectLabel)(usable)) : null,
+        };
+    }
+    catch {
+        return { authenticated: false, subject: null, subjectLabel: null };
+    }
+    finally {
+        if (prevUrl === undefined)
+            delete process.env.ORY_PROJECT_URL;
+        else
+            process.env.ORY_PROJECT_URL = prevUrl;
+        if (prevClient === undefined)
+            delete process.env.ORY_OAUTH2_CLIENT_ID;
+        else
+            process.env.ORY_OAUTH2_CLIENT_ID = prevClient;
+    }
+}
+/** Inspect how the project's permission model relates to the namespace. */
+async function inspectPermissions(runner, projectId, namespace = resolveNamespace()) {
+    const model = await (0, interactive_setup_js_1.inspectPermissionModel)(runner, projectId, namespace);
+    return model.kind === "merge" ? { model: "merge", opl: model.opl } : { model: model.kind };
+}
+/**
+ * Provision (or merge) the namespace into the project's permission model.
+ * Pass `opl` (from a prior `inspectPermissions` "merge" result) to append the
+ * namespace non-destructively; omit it to create a fresh minimal model.
+ */
+function provisionPermissions(runner, projectId, namespace = resolveNamespace(), opl) {
+    return (0, interactive_setup_js_1.provisionPermissionModel)(runner, projectId, namespace, opl);
+}
+/**
+ * Grant `<subject>` the `use` relation on every built-in tool by writing the
+ * relation tuples through the admin-authenticated `ory` CLI. Assumes the
+ * namespace already exists (call {@link inspectPermissions} /
+ * {@link provisionPermissions} first).
+ */
+function grantToolPermissions(runner, projectId, harness, subject, namespace = resolveNamespace()) {
+    const tools = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    if (tools.length === 0)
+        return { ok: true, count: 0 };
+    const subjectPatch = "subjectSet" in subject
+        ? {
+            subject_set: {
+                namespace: subject.subjectSet.namespace,
+                object: subject.subjectSet.object,
+                relation: subject.subjectSet.relation,
+            },
+        }
+        : { subject_id: subject.subjectId };
+    const tuples = tools.map((object) => ({ namespace, object, relation: "use", ...subjectPatch }));
+    const r = runner.exec(["create", "relationships", "--project", projectId, "--format", "json", "-f", "-", "--yes"], { input: JSON.stringify(tuples) });
+    if (r.status === 0)
+        return { ok: true, count: tools.length };
+    return { ok: false, count: 0, error: r.stderr.trim().split("\n")[0] || "unknown error" };
+}
+/**
+ * Ensure a valid project API key is stored for runtime permission *checks*.
+ * No-ops for an env-provided key; validates a stored key and re-mints if it is
+ * dead; otherwise mints one via the Console API and persists it. Best-effort.
+ */
+async function provisionProjectApiKey(input, deps = {}) {
+    const createFn = deps.createProjectApiKeyFn ?? project_api_key_js_1.createProjectApiKeyViaConsole;
+    const validateFn = deps.validateApiKeyFn ?? interactive_setup_js_1.apiKeyAuthenticates;
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (resolved.apiKey) {
+        if (resolved.apiKeySource === "env")
+            return { status: "env" };
+        if (await validateFn(resolved.apiKey, input.projectUrl))
+            return { status: "valid_existing" };
+    }
+    let host = "unknown-host";
+    try {
+        host = os.hostname();
+    }
+    catch {
+        /* keep fallback */
+    }
+    let created = null;
+    try {
+        // Named for the signed-in user + host so a shared project's key list (every
+        // user mints their own) stays attributable and prunable; the Console's
+        // "Date Added" column supplies the timestamp.
+        created = await createFn({
+            projectId: input.projectId,
+            name: (0, branding_js_1.projectApiKeyName)({ host, user: input.user }),
+        });
+    }
+    catch {
+        created = null;
+    }
+    if (created) {
+        // Persist the token id too so uninstall can delete the key server-side.
+        (0, config_js_1.saveConfig)({ apiKey: created.value, apiKeyId: created.id ?? null });
+        return { status: "created" };
+    }
+    return { status: "failed" };
+}
+// ─── audit-only & local stack ─────────────────────────────────────────────
+/** Configure audit-only mode (no project, no auth, no checks). */
+function configureAuditOnly() {
+    (0, config_js_1.saveConfig)({ auditOnly: true });
+}
+// ─── dashboard toggles ────────────────────────────────────────────────────
+/** Set the permission deny posture — `observe` (log) vs `enforce` (block). */
+function setPermissionMode(mode) {
+    (0, config_js_1.saveConfig)({ permissionMode: mode });
+}
+/**
+ * Bring up and seed the local Ory stack, persisting the (stable) local
+ * connection details regardless of whether Docker came up. Mirrors the TTY
+ * wizard's local branch minus the login (the UI drives {@link runFullSetup}
+ * separately). Best-effort throughout.
+ */
+async function configureLocalStack(deps = {}) {
+    const bringUp = deps.localStackFn ?? index_js_1.ensureLocalOryStack;
+    const seed = deps.seedFn ?? index_js_1.seedLocalEnvironment;
+    let status;
+    let detail;
+    try {
+        const stack = await bringUp();
+        status = stack.status;
+        detail = stack.detail;
+    }
+    catch (err) {
+        status = "compose-failed";
+        detail = err instanceof Error ? err.message : String(err);
+    }
+    const running = status === "started" || status === "already-running";
+    (0, config_js_1.saveConfig)({
+        projectUrl: index_js_1.GATEWAY_URL,
+        oauth2ClientId: index_js_1.USER_CLIENT_ID,
+        userSubjectNamespace: index_js_1.USER_SUBJECT_NAMESPACE,
+        auditOnly: false,
+        // The local stack is not an Ory Network project — clear any workspace /
+        // project identifiers left over from a previous Network connection so they
+        // don't linger in config or surface in the dashboard (null deletes the key).
+        projectId: null,
+        projectName: null,
+        workspaceName: null,
+    });
+    const base = {
+        running,
+        detail: running ? undefined : detail ?? status,
+        seeded: false,
+        projectUrl: index_js_1.GATEWAY_URL,
+        oauth2ClientId: index_js_1.USER_CLIENT_ID,
+        subjectNamespace: index_js_1.USER_SUBJECT_NAMESPACE,
+    };
+    if (!running)
+        return base;
+    try {
+        const result = await seed();
+        return {
+            ...base,
+            seeded: true,
+            credentials: {
+                email: result.user.identity.email,
+                password: result.user.password,
+            },
+        };
+    }
+    catch (err) {
+        return { ...base, seedError: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/setup.d.ts

@@ -35,6 +35,25 @@ export declare function isOryHookCommand(h: HookCommand, binName: string): boole
  * Tries require.resolve first, falls back to the global bin name.
  */
 export declare function resolveHookCommand(packageName: string, binName: string): string;
+/**
+ * Pin an `npx` hook command to the local dev registry when the plugin is being
+ * installed against it.
+ *
+ * A runtime hook of `npx -y -p @ory/<h>[@ver] <bin>` re-resolves the plugin on
+ * every invocation. If the harness is launched by hand (not via
+ * `pnpm dev:<harness>`, which sets `npm_config_registry`), that npx defaults to
+ * npmjs.org and runs the last *published* release — so local changes never take
+ * effect. When the install itself is running against the local Verdaccio
+ * registry (detected via `npm_config_registry`, set by both `npx --registry
+ * <local>` and the dev launcher), this stamps `--registry <local>
+ * --min-release-age=0` into the hook so it resolves the freshly published dev
+ * build regardless of how the harness is started.
+ *
+ * A no-op for production installs (npmjs / unset registry) and for non-`npx`
+ * hook commands (e.g. a `node "<path>"` command already runs resolved local
+ * code), so shipped hooks are never altered.
+ */
+export declare function pinHookToLocalRegistry(hookCommand: string): string;
 /**
  * Build a matcher-based hook entry: `[{ matcher: "", hooks: [{ type: "command", command }] }]`
  */

package/dist/setup.js

@@ -38,6 +38,7 @@ exports.readJsonFile = readJsonFile;
 exports.writeJsonFile = writeJsonFile;
 exports.isOryHookCommand = isOryHookCommand;
 exports.resolveHookCommand = resolveHookCommand;
+exports.pinHookToLocalRegistry = pinHookToLocalRegistry;
 exports.matcherHookEntry = matcherHookEntry;
 exports.mergeMatcherHooks = mergeMatcherHooks;
 exports.removeMatcherHooks = removeMatcherHooks;
@@ -60,6 +61,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const cli_invocation_js_1 = require("./cli-invocation.js");
 const config_js_1 = require("./config.js");
+const config_js_2 = require("./registry/config.js");
 const ui = __importStar(require("./ui.js"));
 // ─── Arg Parsing ───────────────────────────────────────────────────
 /**
@@ -139,6 +141,37 @@ function resolveHookCommand(packageName, binName) {
         return binName;
     }
 }
+/**
+ * Pin an `npx` hook command to the local dev registry when the plugin is being
+ * installed against it.
+ *
+ * A runtime hook of `npx -y -p @ory/<h>[@ver] <bin>` re-resolves the plugin on
+ * every invocation. If the harness is launched by hand (not via
+ * `pnpm dev:<harness>`, which sets `npm_config_registry`), that npx defaults to
+ * npmjs.org and runs the last *published* release — so local changes never take
+ * effect. When the install itself is running against the local Verdaccio
+ * registry (detected via `npm_config_registry`, set by both `npx --registry
+ * <local>` and the dev launcher), this stamps `--registry <local>
+ * --min-release-age=0` into the hook so it resolves the freshly published dev
+ * build regardless of how the harness is started.
+ *
+ * A no-op for production installs (npmjs / unset registry) and for non-`npx`
+ * hook commands (e.g. a `node "<path>"` command already runs resolved local
+ * code), so shipped hooks are never altered.
+ */
+function pinHookToLocalRegistry(hookCommand) {
+    const normalize = (u) => u.replace(/\/+$/, "");
+    const active = process.env.npm_config_registry?.trim();
+    if (!active || normalize(active) !== normalize(config_js_2.REGISTRY_URL))
+        return hookCommand;
+    const trimmed = hookCommand.trimStart();
+    if (!/^npx(\s|$)/.test(trimmed))
+        return hookCommand;
+    if (trimmed.includes("--registry"))
+        return hookCommand;
+    // Insert the registry flags right after `npx` (and its optional `-y`).
+    return hookCommand.replace(/^(\s*npx(?:\s+-y)?)(\s)/, `$1 --registry ${config_js_2.REGISTRY_URL} --min-release-age=0$2`);
+}
 // ─── Matcher-Based Hooks (Claude Code, Gemini CLI) ─────────────────
 /**
  * Build a matcher-based hook entry: `[{ matcher: "", hooks: [{ type: "command", command }] }]`
@@ -381,9 +414,7 @@ Environment variables:
   ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
                         ORY_API_KEY is honored as a deprecated alias)
   ORY_OAUTH2_CLIENT_ID  Public OAuth2 client id for the user PKCE flow
-                        (required when ORY_USER_LOGIN=true)
-  ORY_USER_LOGIN        Set to "true" to enable the interactive user login
-                        (or persist it with: configure --user-login)
+                        (the interactive user login runs every session)
   ORY_PERMISSION_MODE   "observe" (default) or "enforce" — what to do on deny
   ORY_AGENT_DEBUG       Set to "true" for debug logging
   ORY_AGENT_LOG_FILE    Path to write debug logs
@@ -454,9 +485,9 @@ function printConfiguredNextStepsNow(harnessName, uninstallCmd, opts) {
     if (auditOnly) {
         ui.hint("Audit-only mode: tool calls are traced locally — no checks run, nothing is blocked.");
         ui.blank();
-        ui.bullet("1. See what's been traced:");
-        ui.command(`${npx} status`);
-        ui.hint(`     ...or watch it live: ${ui.inlineCommand(`${npx} watch`)}`);
+        ui.bullet("1. Open the dashboard — a live view of config, permissions, and activity:");
+        ui.command(`${npx} dashboard`);
+        ui.hint(`     ...or from the terminal: ${ui.inlineCommand(`${npx} status`)} / ${ui.inlineCommand(`${npx} watch`)}`);
         ui.blank();
         ui.bullet("2. Want more detail? Turn on debug logging:");
         ui.command("export ORY_AGENT_DEBUG=true");
@@ -464,9 +495,9 @@ function printConfiguredNextStepsNow(harnessName, uninstallCmd, opts) {
     else {
         ui.hint("It starts in watch mode: every tool call is checked, but nothing is blocked yet.");
         ui.blank();
-        ui.bullet("1. See what Ory is doing — config, permission coverage, recent activity:");
-        ui.command(`${npx} status`);
-        ui.hint(`     ...or watch the trace stream live: ${ui.inlineCommand(`${npx} watch`)}`);
+        ui.bullet("1. Open the dashboard — a live view of config, permission coverage, and activity:");
+        ui.command(`${npx} dashboard`);
+        ui.hint(`     ...or from the terminal: ${ui.inlineCommand(`${npx} status`)} / ${ui.inlineCommand(`${npx} watch`)}`);
         ui.blank();
         ui.bullet("2. Turn on enforcement once the watch-mode traces look right:");
         ui.command(`${npx} permissions enforce`);
@@ -484,12 +515,11 @@ function printNextStepsNow(harnessName, uninstallCmd) {
     ui.command("export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
     ui.command("export ORY_AGENT_API_KEY=ory_pat_...");
     ui.blank();
-    ui.bullet("2. Turn on the interactive user login (opt-in). Either persist it:");
-    ui.command("configure --user-login --oauth2-client-id <public OAuth2 client id>");
-    ui.hint("     ...or set it per-session via env vars:");
-    ui.command("export ORY_USER_LOGIN=true");
+    ui.bullet("2. Provide the public OAuth2 client id for the user login (runs every session):");
+    ui.command("configure --oauth2-client-id <public OAuth2 client id>");
+    ui.hint("     ...or set it per-session via an env var:");
     ui.command("export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
-    ui.hint(`     Without these, ${harnessName} runs without a human Ory identity attached`);
+    ui.hint(`     Without it, ${harnessName} runs without a human Ory identity attached`);
     ui.hint("     to the session and permission checks fall back to a session:<id> subject.");
     ui.hint("     The OAuth2 client id is the public client (no secret) you registered in");
     ui.hint("     your Ory project with the four loopback redirect URIs.");

package/dist/skills.js

@@ -122,6 +122,13 @@ const COMMAND_SOURCES = [
         description: "Start the local Temporal TypeScript dev server (Temporal Server + Web UI) for the Ory-authed worker scaffold.",
         file: "commands/temporal-up.md",
     },
+    {
+        id: "dashboard",
+        name: "ory-dashboard",
+        slug: "dashboard",
+        description: "Open a live browser dashboard of the plugin's configuration and the local Ory stack's service health.",
+        file: "commands/dashboard.md",
+    },
 ];
 /** Names of the skills materialized by the plugins (for uninstall cleanup). */
 exports.ORY_SKILL_NAMES = SKILL_SOURCES.map((s) => s.name);

package/dist/status-cli.d.ts

@@ -1,6 +1,6 @@
 /**
- * Render the "User identity" block. Shows the `ORY_USER_LOGIN` state and,
- * when a PKCE token is cached, the resolved subject and expiry.
+ * Render the "User identity" block. The interactive PKCE login runs every
+ * session; this shows the cached token's subject and expiry, if any.
  */
 export declare function printUserIdentitySection(): void;
 /**