@vforsh/argus 0.1.13 → 0.1.15

package/dist/cli/defineCommand.d.ts

@@ -0,0 +1,26 @@
+import { Command } from 'commander';
+export type ArgusCommandOption = {
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean | string[];
+    required?: boolean;
+};
+export type ArgusCommandDefinition = {
+    name: string;
+    alias?: string;
+    description?: string;
+    arguments?: readonly {
+        flags: string;
+        description: string;
+    }[];
+    options?: readonly ArgusCommandOption[];
+    examples?: readonly string[];
+    configure?: (command: Command) => void;
+    action?: (...args: any[]) => Promise<void> | void;
+    subcommands?: readonly ArgusCommandDefinition[];
+};
+/** Register a declarative command definition with Commander. */
+export declare const defineCommand: (parent: Command, definition: ArgusCommandDefinition) => Command;
+/** Register a list of command definitions in order. */
+export declare const defineCommands: (parent: Command, definitions: readonly ArgusCommandDefinition[]) => void;
+//# sourceMappingURL=defineCommand.d.ts.map

package/dist/cli/defineCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCommand.d.ts","sourceRoot":"","sources":["../../src/cli/defineCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,MAAM,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAA;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC7D,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACjD,WAAW,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;CAC/C,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,aAAa,GAAI,QAAQ,OAAO,EAAE,YAAY,sBAAsB,KAAG,OAgCnF,CAAA;AAED,uDAAuD;AACvD,eAAO,MAAM,cAAc,GAAI,QAAQ,OAAO,EAAE,aAAa,SAAS,sBAAsB,EAAE,KAAG,IAIhG,CAAA"}

package/dist/cli/defineCommand.js

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+/** Register a declarative command definition with Commander. */
+export const defineCommand = (parent, definition) => {
+    const command = parent.command(definition.name);
+    if (definition.alias) {
+        command.alias(definition.alias);
+    }
+    if (definition.description) {
+        command.description(definition.description);
+    }
+    for (const argument of definition.arguments ?? []) {
+        command.argument(argument.flags, argument.description);
+    }
+    for (const option of definition.options ?? []) {
+        if (option.required) {
+            addRequiredOption(command, option);
+        }
+        else {
+            addOption(command, option);
+        }
+    }
+    if (definition.examples && definition.examples.length > 0) {
+        command.addHelpText('after', formatExamples(definition.examples));
+    }
+    definition.configure?.(command);
+    for (const subcommand of definition.subcommands ?? []) {
+        defineCommand(command, subcommand);
+    }
+    if (definition.action) {
+        command.action(definition.action);
+    }
+    return command;
+};
+/** Register a list of command definitions in order. */
+export const defineCommands = (parent, definitions) => {
+    for (const definition of definitions) {
+        defineCommand(parent, definition);
+    }
+};
+const addRequiredOption = (command, option) => {
+    if (option.defaultValue === undefined) {
+        command.requiredOption(option.flags, option.description);
+        return;
+    }
+    command.requiredOption(option.flags, option.description, option.defaultValue);
+};
+const addOption = (command, option) => {
+    if (option.defaultValue === undefined) {
+        command.option(option.flags, option.description);
+        return;
+    }
+    command.option(option.flags, option.description, option.defaultValue);
+};
+const formatExamples = (examples) => `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}\n`;
+//# sourceMappingURL=defineCommand.js.map

package/dist/cli/defineCommand.js.map

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

package/dist/cli/defineWatcherCommand.d.ts

@@ -0,0 +1,112 @@
+import type { ProtocolSchema, WatcherRecord } from '@vforsh/argus-core';
+import type { Output } from '../output/io.js';
+import { requestWatcherAction, type WatcherRequestInput, type WatcherRequestSuccess } from '../watchers/requestWatcher.js';
+/**
+ * Plan for a single watcher HTTP request, produced by a command's `build` step.
+ *
+ * Most commands return a constant plan; commands that adapt the path or timeout
+ * to their inputs (`/storage/<area>`, `Math.max(30s, wait + 5s)`) compute the
+ * plan from `options`. Returning `null` from `build` short-circuits the command
+ * after the build step has written its own warning + set `process.exitCode`.
+ */
+export type WatcherRequestPlan = {
+    /** Request path. May be dynamic (e.g. ``/storage/${area}``). */
+    path: string;
+    /** HTTP method. Defaults to `'POST'` when `body` is set, else `'GET'`. */
+    method?: 'GET' | 'POST';
+    /** Request body. Encoded as JSON. Subject to schema validation when `spec.schema` is set. */
+    body?: unknown;
+    /** Optional query string. */
+    query?: URLSearchParams;
+    /** Override the default 30s timeout. */
+    timeoutMs?: number;
+};
+/**
+ * Shared one-shot request helper for commands that need the watcher metadata
+ * for additional local work instead of a direct JSON/human render pipeline.
+ */
+export declare const requestWatcherCommandJson: <T>(input: WatcherRequestInput, output: Output) => Promise<WatcherRequestSuccess<T> | null>;
+/**
+ * Shared API-action request helper for command support modules that cannot use
+ * `defineWatcherCommand` directly because they compose multiple watcher calls.
+ */
+export declare const requestWatcherCommandAction: typeof requestWatcherAction;
+/** Context passed to `formatHuman` / `formatJson` after a successful request. */
+export type WatcherCommandContext<TArgs extends readonly unknown[], TOptions> = {
+    output: Output;
+    watcher: WatcherRecord;
+    args: TArgs;
+    options: TOptions;
+};
+/**
+ * Spec for a CLI command that talks to a watcher.
+ *
+ * The runner produced by {@link defineWatcherCommand} owns the cross-cutting
+ * pipeline (createOutput → build → optional schema → requestWatcherAction →
+ * JSON-vs-human dispatch). The spec only needs the parts that are unique to
+ * this command.
+ *
+ * `TArgs` is a tuple of positional CLI arguments (excluding the watcher id and
+ * the trailing options object). Most commands use `[]`; commands like `argus
+ * fill <id> <value>` use `[string | undefined]`.
+ */
+export type WatcherCommandSpec<TArgs extends readonly unknown[], TOptions extends {
+    json?: boolean;
+}, TBody, TResponse extends {
+    ok: true;
+}> = {
+    /**
+     * Validate inputs and produce the HTTP request plan. May read stdin/files,
+     * so it can be async. Return `null` to short-circuit (after the build has
+     * already written a warning and set `process.exitCode`).
+     */
+    build: (args: TArgs, options: TOptions, output: Output) => Promise<WatcherRequestPlan | null> | WatcherRequestPlan | null;
+    /**
+     * Treat non-standard flags as JSON mode. Use sparingly for legacy commands
+     * such as `logs --json-full` where JSON output predates the shared `--json`
+     * flag contract.
+     */
+    isJson?: (options: TOptions) => boolean;
+    /**
+     * Optional protocol schema applied to `plan.body` before sending. When the
+     * schema rejects the body, the runner writes the issues and exits with code 2.
+     */
+    schema?: ProtocolSchema<TBody>;
+    /**
+     * Render the success response for human users.
+     * Defaults to compact pretty-printed JSON when omitted.
+     */
+    formatHuman?: (response: TResponse, ctx: WatcherCommandContext<TArgs, TOptions>) => void;
+    /**
+     * Map the success response to the JSON output payload.
+     * Defaults to identity (`response`).
+     */
+    formatJson?: (response: TResponse, ctx: WatcherCommandContext<TArgs, TOptions>) => unknown;
+};
+/**
+ * Runner produced by {@link defineWatcherCommand}. Signature is
+ * `(id, ...args, options) => Promise<void>` — the same shape Commander
+ * action callbacks already use, so the runner drops in unchanged.
+ */
+export type WatcherCommandRunner<TArgs extends readonly unknown[], TOptions> = (id: string | undefined, ...rest: [...TArgs, TOptions]) => Promise<void>;
+/**
+ * Build a runner for a watcher CLI command.
+ *
+ * Pipeline (in order):
+ *  1. `createOutput(options)` — JSON vs human stream selection.
+ *  2. `spec.build(args, options, output)` — validation + body/path/timeout.
+ *     Returning `null` cleanly aborts.
+ *  3. Optional `spec.schema.parse(plan.body)` — protocol validation.
+ *  4. `requestWatcherAction(...)` — resolve watcher + transport + ErrorResponse.
+ *  5. JSON path: write `formatJson?.(...) ?? response`.
+ *  6. Human path: call `formatHuman` (or pretty-print JSON as fallback).
+ *
+ * Type inference resolves `TArgs`/`TOptions`/`TResponse` from the spec, so most
+ * call sites don't need explicit generics.
+ */
+export declare const defineWatcherCommand: <TOptions extends {
+    json?: boolean;
+}, TResponse extends {
+    ok: true;
+}, TBody = unknown, TArgs extends readonly unknown[] = []>(spec: WatcherCommandSpec<TArgs, TOptions, TBody, TResponse>) => WatcherCommandRunner<TArgs, TOptions>;
+//# sourceMappingURL=defineWatcherCommand.d.ts.map

package/dist/cli/defineWatcherCommand.d.ts.map

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

package/dist/cli/defineWatcherCommand.js

@@ -0,0 +1,89 @@
+import { formatProtocolValidationIssues } from '@vforsh/argus-core';
+import { createOutput } from '../output/io.js';
+import { requestWatcherAction, requestWatcherJson, writeRequestError, } from '../watchers/requestWatcher.js';
+/** Default request timeout when a plan does not specify one. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Shared one-shot request helper for commands that need the watcher metadata
+ * for additional local work instead of a direct JSON/human render pipeline.
+ */
+export const requestWatcherCommandJson = async (input, output) => {
+    const result = await requestWatcherJson(input);
+    if (!result.ok) {
+        writeRequestError(result, output);
+        return null;
+    }
+    return result;
+};
+/**
+ * Shared API-action request helper for command support modules that cannot use
+ * `defineWatcherCommand` directly because they compose multiple watcher calls.
+ */
+export const requestWatcherCommandAction = requestWatcherAction;
+/**
+ * Build a runner for a watcher CLI command.
+ *
+ * Pipeline (in order):
+ *  1. `createOutput(options)` — JSON vs human stream selection.
+ *  2. `spec.build(args, options, output)` — validation + body/path/timeout.
+ *     Returning `null` cleanly aborts.
+ *  3. Optional `spec.schema.parse(plan.body)` — protocol validation.
+ *  4. `requestWatcherAction(...)` — resolve watcher + transport + ErrorResponse.
+ *  5. JSON path: write `formatJson?.(...) ?? response`.
+ *  6. Human path: call `formatHuman` (or pretty-print JSON as fallback).
+ *
+ * Type inference resolves `TArgs`/`TOptions`/`TResponse` from the spec, so most
+ * call sites don't need explicit generics.
+ */
+export const defineWatcherCommand = (spec) => async (id, ...rest) => {
+    // `rest` ends with the options object; everything before it is positional CLI args.
+    const tail = rest.length - 1;
+    const options = rest[tail];
+    const args = rest.slice(0, tail);
+    const output = createOutput({ ...options, json: options.json === true || spec.isJson?.(options) === true });
+    const plan = await spec.build(args, options, output);
+    if (plan == null)
+        return;
+    const body = validateBody(plan, spec.schema, output);
+    if (body === SCHEMA_REJECTED)
+        return;
+    const result = await requestWatcherAction({
+        id,
+        path: plan.path,
+        method: plan.method ?? (plan.body !== undefined ? 'POST' : 'GET'),
+        body,
+        query: plan.query,
+        timeoutMs: plan.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    }, output);
+    if (!result)
+        return;
+    const ctx = { output, watcher: result.watcher, args, options };
+    if (output.json) {
+        output.writeJson(spec.formatJson ? spec.formatJson(result.data, ctx) : result.data);
+        return;
+    }
+    if (spec.formatHuman) {
+        spec.formatHuman(result.data, ctx);
+        return;
+    }
+    output.writeHuman(JSON.stringify(result.data, null, 2));
+};
+/** Sentinel returned by {@link validateBody} when schema validation failed. */
+const SCHEMA_REJECTED = Symbol('schema-rejected');
+/**
+ * Validate `plan.body` against an optional schema. On failure, write a warning,
+ * set `process.exitCode = 2`, and return {@link SCHEMA_REJECTED} so the caller
+ * can early-exit. On success (or when no schema is provided), return the body
+ * to send.
+ */
+const validateBody = (plan, schema, output) => {
+    if (!schema || plan.body === undefined)
+        return plan.body;
+    const parsed = schema.parse(plan.body);
+    if (parsed.ok)
+        return parsed.value;
+    output.writeWarn(formatProtocolValidationIssues(parsed.issues));
+    process.exitCode = 2;
+    return SCHEMA_REJECTED;
+};
+//# sourceMappingURL=defineWatcherCommand.js.map

package/dist/cli/defineWatcherCommand.js.map

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

package/dist/cli/plugins/pluginAliases.d.ts

@@ -0,0 +1,6 @@
+export declare const BUILTIN_PLUGIN_ALIASES: Record<string, string>;
+export declare const resolvePluginAlias: (spec: string, aliases: Record<string, string>) => {
+    spec: string;
+    alias: string | null;
+};
+//# sourceMappingURL=pluginAliases.d.ts.map

package/dist/cli/plugins/pluginAliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginAliases.d.ts","sourceRoot":"","sources":["../../../src/cli/plugins/pluginAliases.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGzD,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAItH,CAAA"}

package/dist/cli/plugins/pluginAliases.js

@@ -0,0 +1,10 @@
+export const BUILTIN_PLUGIN_ALIASES = {
+    gsheets: '@vforsh/argus-plugin-google-sheets',
+    gs: '@vforsh/argus-plugin-google-sheets',
+};
+export const resolvePluginAlias = (spec, aliases) => {
+    const trimmed = spec.trim();
+    const resolved = aliases[trimmed];
+    return resolved ? { spec: resolved, alias: trimmed } : { spec: trimmed, alias: null };
+};
+//# sourceMappingURL=pluginAliases.js.map

package/dist/cli/plugins/pluginAliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginAliases.js","sourceRoot":"","sources":["../../../src/cli/plugins/pluginAliases.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC7D,OAAO,EAAE,oCAAoC;IAC7C,EAAE,EAAE,oCAAoC;CACxC,CAAA;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAY,EAAE,OAA+B,EAA0C,EAAE;IAC3H,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACtF,CAAC,CAAA"}

package/dist/cli/plugins/pluginHost.d.ts

@@ -0,0 +1,3 @@
+import type { ArgusPluginHostV1 } from '@vforsh/argus-plugin-api';
+export declare const createPluginHost: () => ArgusPluginHostV1;
+//# sourceMappingURL=pluginHost.d.ts.map

package/dist/cli/plugins/pluginHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginHost.d.ts","sourceRoot":"","sources":["../../../src/cli/plugins/pluginHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkD,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AA2BjH,eAAO,MAAM,gBAAgB,QAAO,iBAOlC,CAAA"}

package/dist/cli/plugins/pluginHost.js

@@ -0,0 +1,30 @@
+import { createOutput } from '../../output/io.js';
+import { runChromeOpen } from '../../commands/chrome.js';
+import { defineWatcherCommand } from '../defineWatcherCommand.js';
+import { requestWatcherJson, writeRequestError } from '../../watchers/requestWatcher.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const postWatcherJson = (id, path, body, timeoutMs = DEFAULT_TIMEOUT_MS) => requestWatcherJson({
+    id,
+    path,
+    method: 'POST',
+    body,
+    timeoutMs,
+});
+const argus = {
+    eval: (id, request, options) => postWatcherJson(id, '/eval', request, options?.timeoutMs ?? request.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    dom: {
+        click: (id, request, options) => postWatcherJson(id, '/dom/click', request, options?.timeoutMs),
+        info: (id, request, options) => postWatcherJson(id, '/dom/info', request, options?.timeoutMs),
+        keydown: (id, request, options) => postWatcherJson(id, '/dom/keydown', request, options?.timeoutMs),
+    },
+    screenshot: (id, request = {}, options) => postWatcherJson(id, '/screenshot', request, options?.timeoutMs),
+};
+export const createPluginHost = () => ({
+    createOutput,
+    requestWatcherJson,
+    writeRequestError,
+    runChromeOpen,
+    defineWatcherCommand: defineWatcherCommand,
+    argus,
+});
+//# sourceMappingURL=pluginHost.js.map

package/dist/cli/plugins/pluginHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginHost.js","sourceRoot":"","sources":["../../../src/cli/plugins/pluginHost.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAExF,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEjC,MAAM,eAAe,GAAG,CAAI,EAAsB,EAAE,IAAY,EAAE,IAAa,EAAE,SAAS,GAAG,kBAAkB,EAAE,EAAE,CAClH,kBAAkB,CAAI;IACrB,EAAE;IACF,IAAI;IACJ,MAAM,EAAE,MAAM;IACd,IAAI;IACJ,SAAS;CACT,CAAC,CAAA;AAEH,MAAM,KAAK,GAAwB;IAClC,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACpI,GAAG,EAAE;QACJ,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;QAC/F,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;QAC7F,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;KACnG;IACD,UAAU,EAAE,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;CAC1G,CAAA;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAsB,EAAE,CAAC,CAAC;IACzD,YAAY;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,aAAa;IACb,oBAAoB,EAAE,oBAAiD;IACvE,KAAK;CACL,CAAC,CAAA"}

package/dist/cli/plugins/registerPlugins.d.ts

@@ -1,3 +1,34 @@
 import type { Command } from 'commander';
-export declare const registerPlugins: (program: Command) => Promise<void>;
+type PluginSource = 'config' | 'env' | 'cli';
+export type PluginLoadEntry = {
+    source: PluginSource;
+    spec: string;
+    resolvedSpec: string;
+    alias: string | null;
+    status: 'loaded';
+    name: string;
+    version: string | null;
+    description: string | null;
+    commands: string[];
+    homepage: string | null;
+    minArgusVersion: string | null;
+    url: string;
+} | {
+    source: PluginSource;
+    spec: string;
+    resolvedSpec: string;
+    alias: string | null;
+    status: 'failed';
+    error: string;
+    url?: string;
+};
+export type PluginLoadReport = {
+    configPath: string | null;
+    configDir: string | null;
+    cwd: string;
+    entries: PluginLoadEntry[];
+};
+export declare const getPluginLoadReport: () => PluginLoadReport;
+export declare const registerPlugins: (program: Command, argv?: readonly string[]) => Promise<void>;
+export {};
 //# sourceMappingURL=registerPlugins.d.ts.map

package/dist/cli/plugins/registerPlugins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registerPlugins.d.ts","sourceRoot":"","sources":["../../../src/cli/plugins/registerPlugins.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAsFxC,eAAO,MAAM,eAAe,GAAU,SAAS,OAAO,KAAG,OAAO,CAAC,IAAI,CA8DpE,CAAA"}
+{"version":3,"file":"registerPlugins.d.ts","sourceRoot":"","sources":["../../../src/cli/plugins/registerPlugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAOxC,KAAK,YAAY,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAA;AAS5C,MAAM,MAAM,eAAe,GACxB;IACA,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,QAAQ,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,EAAE,MAAM,CAAA;CACV,GACD;IACA,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,QAAQ,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;CACX,CAAA;AAEJ,MAAM,MAAM,gBAAgB,GAAG;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AASD,eAAO,MAAM,mBAAmB,QAAO,gBAAwC,CAAA;AA0J/E,eAAO,MAAM,eAAe,GAAU,SAAS,OAAO,EAAE,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA+ErH,CAAA"}

package/dist/cli/plugins/registerPlugins.js

@@ -1,10 +1,18 @@
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { ARGUS_PLUGIN_API_VERSION } from '@vforsh/argus-plugin-api';
 import { resolveArgusConfigPath, loadArgusConfig } from '../../config/argusConfig.js';
 import { createOutput } from '../../output/io.js';
-import { requestWatcherJson, writeRequestError } from '../../watchers/requestWatcher.js';
-import { runChromeOpen } from '../../commands/chrome.js';
+import { BUILTIN_PLUGIN_ALIASES, resolvePluginAlias } from './pluginAliases.js';
+import { createPluginHost } from './pluginHost.js';
+let lastPluginLoadReport = {
+    configPath: null,
+    configDir: null,
+    cwd: process.cwd(),
+    entries: [],
+};
+export const getPluginLoadReport = () => lastPluginLoadReport;
 const parseEnvPlugins = () => {
     const raw = process.env.ARGUS_PLUGINS;
     if (!raw)
@@ -15,6 +23,31 @@ const parseEnvPlugins = () => {
         .filter(Boolean);
 };
 const uniq = (values) => Array.from(new Set(values));
+const createPluginInput = (source, spec, aliases) => {
+    const resolved = resolvePluginAlias(spec, aliases);
+    return { source, spec, resolvedSpec: resolved.spec, alias: resolved.alias };
+};
+/** Plugins must be loaded before Commander parses commands, so scan raw argv for dynamic loads. */
+const parseCliPlugins = (argv) => {
+    const plugins = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--plugin') {
+            const value = argv[i + 1];
+            if (value && !value.startsWith('-')) {
+                plugins.push(value);
+                i++;
+            }
+            continue;
+        }
+        if (arg.startsWith('--plugin=')) {
+            const value = arg.slice('--plugin='.length).trim();
+            if (value)
+                plugins.push(value);
+        }
+    }
+    return plugins;
+};
 const resolveWithImportMeta = (specifier, parentUrl) => {
     const resolver = import.meta.resolve;
     if (typeof resolver !== 'function') {
@@ -22,6 +55,7 @@ const resolveWithImportMeta = (specifier, parentUrl) => {
     }
     return resolver(specifier, parentUrl);
 };
+const isPathLikeSpecifier = (specifier) => specifier.startsWith('.') || specifier.startsWith('/');
 const resolvePluginModuleUrl = (specifier, baseDirs) => {
     const trimmed = specifier.trim();
     if (!trimmed) {
@@ -31,6 +65,22 @@ const resolvePluginModuleUrl = (specifier, baseDirs) => {
         return { ok: true, url: trimmed };
     }
     const errors = [];
+    if (isPathLikeSpecifier(trimmed)) {
+        for (const baseDir of baseDirs) {
+            try {
+                const resolvedPath = path.resolve(baseDir, trimmed);
+                if (existsSync(resolvedPath)) {
+                    return { ok: true, url: pathToFileURL(resolvedPath).href };
+                }
+                errors.push(`${baseDir}: ${resolvedPath} does not exist`);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                errors.push(`${baseDir}: ${msg}`);
+            }
+        }
+        return { ok: false, error: `Failed to resolve plugin path "${specifier}". Tried:\n${errors.map((e) => `- ${e}`).join('\n')}` };
+    }
     // 1) Prefer resolving relative to the Argus installation itself.
     // This covers "plugin installed next to argus" (e.g. global install or argus dependency).
     try {
@@ -68,27 +118,66 @@ const extractPlugin = (mod) => {
         return null;
     return plugin;
 };
+const normalizeOptionalString = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+const normalizeCommands = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const commands = value
+        .filter((item) => typeof item === 'string')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return Array.from(new Set(commands));
+};
 const warnPluginLoad = (source, spec, message) => {
     const output = createOutput({ json: false });
     output.writeWarn(`[plugins] Failed to load (${source}) "${spec}": ${message}`);
 };
-export const registerPlugins = async (program) => {
+const recordPluginFailure = (entries, entry, error, url) => {
+    entries.push({ source: entry.source, spec: entry.spec, resolvedSpec: entry.resolvedSpec, alias: entry.alias, status: 'failed', url, error });
+    warnPluginLoad(entry.source, entry.spec, error);
+};
+const createLoadedEntry = (entry, plugin, url) => ({
+    source: entry.source,
+    spec: entry.spec,
+    resolvedSpec: entry.resolvedSpec,
+    alias: entry.alias,
+    status: 'loaded',
+    name: plugin.name,
+    version: normalizeOptionalString(plugin.version),
+    description: normalizeOptionalString(plugin.description),
+    commands: normalizeCommands(plugin.commands),
+    homepage: normalizeOptionalString(plugin.homepage),
+    minArgusVersion: normalizeOptionalString(plugin.minArgusVersion),
+    url,
+});
+export const registerPlugins = async (program, argv = process.argv.slice(2)) => {
     const cwd = process.cwd();
     const configPath = resolveArgusConfigPath({ cwd });
     const configResult = configPath ? loadArgusConfig(configPath) : null;
+    const aliases = { ...BUILTIN_PLUGIN_ALIASES, ...(configResult?.config.pluginAliases ?? {}) };
     const configPlugins = configResult?.config.plugins ?? [];
     const envPlugins = parseEnvPlugins();
+    const cliPlugins = parseCliPlugins(argv);
     const all = [];
     for (const spec of configPlugins)
-        all.push({ source: 'config', spec });
+        all.push(createPluginInput('config', spec, aliases));
     for (const spec of envPlugins)
-        all.push({ source: 'env', spec });
+        all.push(createPluginInput('env', spec, aliases));
+    for (const spec of cliPlugins)
+        all.push(createPluginInput('cli', spec, aliases));
+    const entries = [];
+    lastPluginLoadReport = {
+        configPath,
+        configDir: configResult?.configDir ?? null,
+        cwd,
+        entries,
+    };
     if (all.length === 0)
         return;
     // Preserve original order, but avoid duplicate loads.
     const seen = new Set();
     const ordered = all.filter((p) => {
-        const key = p.spec.trim();
+        const key = p.resolvedSpec.trim();
         if (!key)
             return false;
         if (seen.has(key))
@@ -99,15 +188,15 @@ export const registerPlugins = async (program) => {
     const baseDirs = uniq([configResult?.configDir, cwd].filter((v) => Boolean(v)));
     const ctxBase = {
         apiVersion: ARGUS_PLUGIN_API_VERSION,
-        host: { createOutput, requestWatcherJson, writeRequestError, runChromeOpen },
+        host: createPluginHost(),
         cwd,
         configPath,
         configDir: configResult?.configDir ?? null,
     };
     for (const entry of ordered) {
-        const resolved = resolvePluginModuleUrl(entry.spec, baseDirs);
+        const resolved = resolvePluginModuleUrl(entry.resolvedSpec, baseDirs);
         if (!resolved.ok) {
-            warnPluginLoad(entry.source, entry.spec, resolved.error);
+            recordPluginFailure(entries, entry, resolved.error);
             continue;
         }
         let mod;
@@ -115,19 +204,20 @@ export const registerPlugins = async (program) => {
             mod = await import(resolved.url);
         }
         catch (error) {
-            warnPluginLoad(entry.source, entry.spec, error instanceof Error ? error.message : String(error));
+            recordPluginFailure(entries, entry, error instanceof Error ? error.message : String(error), resolved.url);
             continue;
         }
         const plugin = extractPlugin(mod);
         if (!plugin) {
-            warnPluginLoad(entry.source, entry.spec, 'Invalid plugin export (expected default export with { apiVersion: 1, name, register() }).');
+            recordPluginFailure(entries, entry, 'Invalid plugin export (expected default export with { apiVersion: 1, name, register() }).', resolved.url);
             continue;
         }
         try {
             await plugin.register({ ...ctxBase, program });
+            entries.push(createLoadedEntry(entry, plugin, resolved.url));
         }
         catch (error) {
-            warnPluginLoad(entry.source, entry.spec, error instanceof Error ? error.message : String(error));
+            recordPluginFailure(entries, entry, error instanceof Error ? error.message : String(error), resolved.url);
         }
     }
 };