@portqueue/cli 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +21 -2
  3. package/dist/args.d.ts +25 -0
  4. package/dist/args.test.d.ts +1 -0
  5. package/dist/basic-auth.d.ts +12 -0
  6. package/dist/basic-auth.test.d.ts +1 -0
  7. package/dist/cli.d.ts +1 -0
  8. package/dist/cli.mjs +8 -0
  9. package/dist/cli.mjs.map +1 -0
  10. package/dist/commands/add.d.ts +3 -0
  11. package/dist/commands/add.test.d.ts +1 -0
  12. package/dist/commands/cancel.d.ts +3 -0
  13. package/dist/commands/cancel.test.d.ts +1 -0
  14. package/dist/commands/dashboard.d.ts +3 -0
  15. package/dist/commands/doctor.d.ts +3 -0
  16. package/dist/commands/doctor.test.d.ts +1 -0
  17. package/dist/commands/helpers.d.ts +30 -0
  18. package/dist/commands/helpers.test.d.ts +1 -0
  19. package/dist/commands/index.d.ts +8 -0
  20. package/dist/commands/instances.d.ts +5 -0
  21. package/dist/commands/instances.test.d.ts +1 -0
  22. package/dist/commands/jobs.d.ts +5 -0
  23. package/dist/commands/jobs.test.d.ts +1 -0
  24. package/dist/commands/listen.d.ts +3 -0
  25. package/dist/commands/migrate.d.ts +3 -0
  26. package/dist/commands/migrate.test.d.ts +1 -0
  27. package/dist/commands/pause.d.ts +5 -0
  28. package/dist/commands/pause.test.d.ts +1 -0
  29. package/dist/commands/purge.d.ts +3 -0
  30. package/dist/commands/purge.test.d.ts +1 -0
  31. package/dist/commands/queues.d.ts +3 -0
  32. package/dist/commands/queues.test.d.ts +1 -0
  33. package/dist/commands/registry.test.d.ts +1 -0
  34. package/dist/commands/remove-instance.d.ts +3 -0
  35. package/dist/commands/remove-queue.d.ts +3 -0
  36. package/dist/commands/remove.d.ts +3 -0
  37. package/dist/commands/remove.test.d.ts +1 -0
  38. package/dist/commands/retry.d.ts +3 -0
  39. package/dist/commands/retry.test.d.ts +1 -0
  40. package/dist/commands/schedules.d.ts +3 -0
  41. package/dist/commands/schedules.test.d.ts +1 -0
  42. package/dist/commands/stats.d.ts +3 -0
  43. package/dist/commands/stats.test.d.ts +1 -0
  44. package/dist/commands/types.d.ts +40 -0
  45. package/dist/driver.d.ts +34 -0
  46. package/dist/driver.test.d.ts +1 -0
  47. package/dist/errors.d.ts +3 -0
  48. package/dist/help.d.ts +2 -0
  49. package/dist/help.test.d.ts +1 -0
  50. package/dist/index.d.ts +4 -0
  51. package/dist/index.mjs +8 -0
  52. package/dist/index.mjs.map +1 -0
  53. package/dist/output.d.ts +33 -0
  54. package/dist/output.test.d.ts +1 -0
  55. package/dist/run-gA8fFpEb.js +1053 -0
  56. package/dist/run-gA8fFpEb.js.map +1 -0
  57. package/dist/run.d.ts +1 -0
  58. package/dist/run.test.d.ts +1 -0
  59. package/dist/test-support/capture.d.ts +5 -0
  60. package/dist/test-support/fake-pq.d.ts +41 -0
  61. package/dist/test-support/run-command.d.ts +20 -0
  62. package/package.json +60 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PortQueue contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,22 @@
1
- # Temporary Holding Version
1
+ # @portqueue/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The command-line tool for monitoring and operating [PortQueue](https://episclera.github.io/portqueue/), and for serving the dashboard.
4
+
5
+ ```bash
6
+ npm install -D @portqueue/cli
7
+ ```
8
+
9
+ It builds its own short-lived, **headless** client from `--driver`/`--connection-string` (or `DATABASE_URL`): it declares no queues, registers no instance row, and consumes no queue or scheduler, so an admin command never joins the cluster it is inspecting.
10
+
11
+ ```bash
12
+ portqueue stats --watch
13
+ portqueue queues
14
+ portqueue jobs --queue emails --status FAILED
15
+ portqueue add --queue emails --data '{"to":"a@b.com"}'
16
+ portqueue retry --id <jobId> --from failed
17
+ portqueue pause --queue emails --mode processing
18
+ portqueue listen # stream events infinitely
19
+ portqueue dashboard --port 4321 --root-user admin --root-password ****
20
+ ```
21
+
22
+ Run `portqueue --help` for the full command list. **MIT** — free for commercial use, no obligations.
package/dist/args.d.ts ADDED
@@ -0,0 +1,25 @@
1
+ /**
2
+ * A tiny dependency-free argv parser: subcommands + `--flag value`
3
+ * (and `--bool`). No positional soup. `--` is not needed; the first non-flag token is the
4
+ * (sub)command path.
5
+ *
6
+ * One rule earns its own list below: a **boolean flag never consumes the token after it**. Without
7
+ * that, `portqueue --json jobs` parsed as `{ json: 'jobs' }` with no command at all and printed
8
+ * help — and `help.ts` advertises `--json`/`--no-color` as global, which invites exactly that
9
+ * ordering.
10
+ */
11
+ export interface ParsedArgs {
12
+ command: string[];
13
+ flags: Record<string, string | boolean>;
14
+ positionals: string[];
15
+ }
16
+ /**
17
+ * Every flag that is a switch rather than a setting. Kept as one list because the alternative —
18
+ * inferring from what follows — cannot tell `--json jobs` (a flag and a command) from
19
+ * `--queue jobs` (a flag and its value).
20
+ */
21
+ export declare const BOOLEAN_FLAGS: ReadonlySet<string>;
22
+ export declare function parseArgs(argv: string[]): ParsedArgs;
23
+ export declare function flagString(flags: Record<string, string | boolean>, name: string): string | undefined;
24
+ export declare function flagNumber(flags: Record<string, string | boolean>, name: string): number | undefined;
25
+ export declare function flagBool(flags: Record<string, string | boolean>, name: string): boolean;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,12 @@
1
+ import { IncomingMessage, ServerResponse } from 'node:http';
2
+ export interface BasicAuthOptions {
3
+ username: string;
4
+ password: string;
5
+ /** Shown in the browser's credential prompt. */
6
+ realm?: string;
7
+ }
8
+ /**
9
+ * A `(req, res) => boolean` gate: returns true when the request is authorized and the caller
10
+ * should carry on, false when it has already been answered with a 401 challenge.
11
+ */
12
+ export declare function createBasicAuthGuard(options: BasicAuthOptions): (req: IncomingMessage, res: ServerResponse) => boolean;
@@ -0,0 +1 @@
1
+ export {};
package/dist/cli.d.ts ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/cli.mjs ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ import { r as run } from "./run-gA8fFpEb.js";
3
+ run(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
4
+ process.stderr.write(`${err.stack ?? err}
5
+ `);
6
+ process.exit(1);
7
+ });
8
+ //# sourceMappingURL=cli.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.mjs","sources":["../src/cli.ts"],"sourcesContent":["import { run } from './run';\n\nrun(process.argv.slice(2))\n .then((code) => process.exit(code))\n .catch((err) => {\n process.stderr.write(`${(err as Error).stack ?? err}\\n`);\n process.exit(1);\n });\n"],"names":[],"mappings":";;AAEA,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC,EACtB,KAAK,CAAC,SAAS,QAAQ,KAAK,IAAI,CAAC,EACjC,MAAM,CAAC,QAAQ;AACd,UAAQ,OAAO,MAAM,GAAI,IAAc,SAAS,GAAG;AAAA,CAAI;AACvD,UAAQ,KAAK,CAAC;AAChB,CAAC;"}
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue add --queue --data <json|@file> [job/schedule flags]` */
3
+ export declare const addCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue cancel --id` */
3
+ export declare const cancelCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue dashboard --port --root-user --root-password [--host --base-path]` */
3
+ export declare const dashboardCommand: Command;
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue doctor [--json]` */
3
+ export declare const doctorCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,30 @@
1
+ import { JobStatus } from '@portqueue/core';
2
+ import { Flags } from './types';
3
+ /** Read a required string flag, or throw an actionable error naming it. */
4
+ export declare function requireFlag(flags: Flags, name: string): string;
5
+ /** Parse a `--status` flag into a `JobStatus`, validating against the enum. */
6
+ export declare function parseStatus(value: string | undefined): JobStatus | undefined;
7
+ /** The paging window a list command was asked for, in the shape every public query takes. */
8
+ export interface PageFlags {
9
+ limit?: number;
10
+ offset?: number;
11
+ }
12
+ /**
13
+ * Parse `--limit` / `--offset`.
14
+ *
15
+ * Tested with `!== undefined` rather than truthiness, which is what made `--limit 0` silently mean
16
+ * "unset" and page the default 50 rows. A zero or negative limit is a mistake, so it says so.
17
+ */
18
+ export declare function pageFlags(flags: Flags): PageFlags;
19
+ /**
20
+ * Print the "there is more" hint after a page, if there is.
21
+ *
22
+ * Shared by every paged list so all of them say it the same way — `schedules` used to say nothing at
23
+ * all, which made a deployment with more than one page of schedules look like it had one.
24
+ */
25
+ export declare function printMoreHint(page: {
26
+ items: unknown[];
27
+ total: number;
28
+ }, offset?: number): void;
29
+ /** The `[--limit <n> --offset <n>]` fragment every paged command shows in help. */
30
+ export declare const PAGE_USAGE = "[--limit <n> --offset <n>]";
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,8 @@
1
+ import { Command } from './types';
2
+ /**
3
+ * The command registry. Both dispatch (`COMMANDS_BY_NAME`) and the generated help
4
+ * are derived from this single list — add a command here and it appears everywhere.
5
+ */
6
+ export declare const COMMANDS: readonly Command[];
7
+ export declare const COMMANDS_BY_NAME: ReadonlyMap<string, Command>;
8
+ export { CommandGroup, type Command, type CommandContext } from './types';
@@ -0,0 +1,5 @@
1
+ import { Command } from './types';
2
+ /** `portqueue instances [--limit <n> --offset <n>]` */
3
+ export declare const instancesCommand: Command;
4
+ /** `portqueue instance --key <instanceKey>` */
5
+ export declare const instanceCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,5 @@
1
+ import { Command } from './types';
2
+ /** `portqueue jobs [--queue] [--status] [--schedule-id] [--limit --offset]` */
3
+ export declare const jobsCommand: Command;
4
+ /** `portqueue job --id <jobId>` */
5
+ export declare const jobCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue listen [--queue] [--events ...]` — runs infinitely, streaming events. */
3
+ export declare const listenCommand: Command;
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue migrate [--mode auto|validate-only]` */
3
+ export declare const migrateCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,5 @@
1
+ import { Command } from './types';
2
+ /** `portqueue pause --queue [--mode processing|all]` */
3
+ export declare const pauseCommand: Command;
4
+ /** `portqueue resume --queue` */
5
+ export declare const resumeCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue purge --queue --status --yes` */
3
+ export declare const purgeCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue queues [--limit <n> --offset <n>]` */
3
+ export declare const queuesCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue remove-instance --instance-key <key>` */
3
+ export declare const removeInstanceCommand: Command;
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue remove-queue --queue <name>` */
3
+ export declare const removeQueueCommand: Command;
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue remove (--id <jobId> | --schedule-id <id>)` */
3
+ export declare const removeCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue retry --id <jobId>` — re-arm a settled job so it runs again. */
3
+ export declare const retryCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue schedules [--queue <name>] [--limit <n> --offset <n>]` */
3
+ export declare const schedulesCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { Command } from './types';
2
+ /** `portqueue stats [--queue] [--watch]` */
3
+ export declare const statsCommand: Command;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,40 @@
1
+ import { PortQueue } from '@portqueue/core';
2
+ import { ParsedArgs } from '../args';
3
+ export type Flags = ParsedArgs['flags'];
4
+ /** Something a command opened and the runner must close on the way out. */
5
+ export type Teardown = () => void | Promise<void>;
6
+ /** Everything a command needs to run: the resolved instance + parsed flags. */
7
+ export interface CommandContext {
8
+ readonly pq: PortQueue;
9
+ readonly flags: Flags;
10
+ /**
11
+ * Register a resource to release when the process stops — a listening server, an interval, a
12
+ * dashboard mount. The runner calls these newest-first before shutting the client down, on a clean
13
+ * exit, on a signal, and on a throw. A persistent command that opens anything must use this: an
14
+ * interval whose handle is dropped keeps the loop alive with nothing to stop it, and a bound port
15
+ * outlives the client it was serving.
16
+ */
17
+ readonly onExit: (teardown: Teardown) => void;
18
+ }
19
+ /** Section a command appears under in the generated help output. */
20
+ export declare enum CommandGroup {
21
+ Monitoring = "Monitoring",
22
+ Actions = "Actions",
23
+ Operational = "Operational"
24
+ }
25
+ /**
26
+ * A self-describing CLI command. The registry (`commands/index.ts`) derives both
27
+ * dispatch and help from this shape, so there is no separate map or help string to
28
+ * keep in sync. Options arrive as a single named `CommandContext` — never positional.
29
+ */
30
+ export interface Command {
31
+ readonly name: string;
32
+ readonly group: CommandGroup;
33
+ /** One-line summary shown in help. */
34
+ readonly summary: string;
35
+ /** Argument spec shown after the command name in help (flags etc.). */
36
+ readonly usage?: string;
37
+ /** Long-running commands (stream/serve) keep the instance alive after `run` returns. */
38
+ readonly persistent?: boolean;
39
+ run(ctx: CommandContext): Promise<void>;
40
+ }
@@ -0,0 +1,34 @@
1
+ import { PortQueue, Driver } from '@portqueue/core';
2
+ /** The engines the CLI can construct a driver for. */
3
+ export declare enum CliEngine {
4
+ POSTGRES = "postgres",
5
+ PGLITE = "pglite",
6
+ SQLITE = "sqlite",
7
+ MYSQL = "mysql",
8
+ ORACLE = "oracle"
9
+ }
10
+ /** Flags that describe how to connect to the database. */
11
+ export interface DriverFlags {
12
+ driver?: string | undefined;
13
+ connectionString?: string | undefined;
14
+ schema?: string | undefined;
15
+ tablePrefix?: string | undefined;
16
+ namespace?: string | undefined;
17
+ }
18
+ /**
19
+ * Builds the CLI's own short-lived PortQueue from connection flags. It never loads the user's app
20
+ * config: it constructs a driver from `--driver`/`--connection-string` (or `DATABASE_URL`) and
21
+ * returns a **headless** client (`_headless: true`).
22
+ *
23
+ * Headless is what keeps an admin tool from behaving like a participant: it declares no queues and
24
+ * writes no queue rows, registers no instance row (so `portqueue instances` never shows the CLI
25
+ * itself), and consumes no queue, so it runs no claim loop, scheduler or retention sweep.
26
+ *
27
+ * Migration is the one thing the CLI opts back into. A headless client defaults to `MANUAL` — that
28
+ * default exists for the dashboard, which must never change a schema by being pointed at it — but
29
+ * bringing a schema up to date is squarely the CLI's remit, and a fresh database should answer
30
+ * `portqueue queues` rather than an error about a missing table.
31
+ */
32
+ export declare function buildPortQueue(flags: DriverFlags): Promise<PortQueue>;
33
+ /** The driver alone, for the `dashboard` command — `createDashboard` builds its own client. */
34
+ export declare function buildDriver(flags: DriverFlags): Promise<Driver>;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ /** The one error type the CLI throws for actionable, user-facing failures. */
2
+ export declare class CliError extends Error {
3
+ }
package/dist/help.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** Build the help text from the command registry so it can never drift from reality. */
2
+ export declare function renderHelp(): string;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,4 @@
1
+ export { run } from './run';
2
+ export { parseArgs } from './args';
3
+ export { buildPortQueue, CliEngine } from './driver';
4
+ export type { DriverFlags } from './driver';
package/dist/index.mjs ADDED
@@ -0,0 +1,8 @@
1
+ import { C, b, p, r } from "./run-gA8fFpEb.js";
2
+ export {
3
+ C as CliEngine,
4
+ b as buildPortQueue,
5
+ p as parseArgs,
6
+ r as run
7
+ };
8
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
@@ -0,0 +1,33 @@
1
+ import { JobStatus } from '@portqueue/core';
2
+ type Ansi = keyof typeof CODES;
3
+ declare const CODES: {
4
+ reset: string;
5
+ dim: string;
6
+ bold: string;
7
+ red: string;
8
+ green: string;
9
+ yellow: string;
10
+ blue: string;
11
+ magenta: string;
12
+ cyan: string;
13
+ gray: string;
14
+ };
15
+ export declare function setColorEnabled(enabled: boolean): void;
16
+ export declare function color(text: string, ...styles: Ansi[]): string;
17
+ /** Semantic color per job status, mirroring the dashboard StatusTag. */
18
+ export declare function colorStatus(status: JobStatus | string): string;
19
+ export declare const symbols: {
20
+ ok: () => string;
21
+ warn: () => string;
22
+ err: () => string;
23
+ };
24
+ export declare function success(message: string): void;
25
+ export declare function warn(message: string): void;
26
+ export declare function fail(message: string): void;
27
+ export declare function heading(text: string): void;
28
+ /** Render a simple aligned table. */
29
+ export declare function table(headers: string[], rows: string[][]): void;
30
+ /** Human-friendly relative time. */
31
+ export declare function relativeTime(date: Date | null | undefined, now?: number): string;
32
+ export declare function printJson(value: unknown): void;
33
+ export {};
@@ -0,0 +1 @@
1
+ export {};