procdeck 0.1.0 → 0.3.0

package/dist/public.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The package's public entry point — everything a `procdeck.config.ts` needs.
+ *
+ * The types are written out structurally instead of being derived from the
+ * Effect schema in `config.ts`, because a derived type makes the emitted `.d.ts`
+ * import `effect`, and effect is bundled into the CLI rather than installed:
+ * consumers would be typechecking against a package they don't have.
+ *
+ * `tests/public.test.ts` asserts at the type level that this mirrors the schema
+ * exactly, so the two cannot drift apart silently.
+ */
+/** A check that must pass before the proc spawns; failure parks it in `blocked`. */
+export type Preflight = {
+    /** Shell command; exit 0 lets the proc spawn. */
+    readonly shell: string;
+    /** Regex the check's output must also match, for checks that exit 0 either way. */
+    readonly expect?: string;
+    /** What the human should do when the check fails. */
+    readonly hint?: string;
+};
+/** A regex watched in the pane output; a match raises a badge in the UI. */
+export type Alert = {
+    readonly pattern: string;
+    /** Badge text. */
+    readonly label: string;
+};
+/** A single supervised process. Exactly one of `shell` / `cmd` is used. */
+export type ProcSpec = {
+    /** Pane label and proxy subdomain (`api` → http://api.localhost:4820). */
+    readonly id: string;
+    /** Command line handed to `$SHELL -c`. */
+    readonly shell?: string;
+    /** argv, executed without a shell. */
+    readonly cmd?: ReadonlyArray<string>;
+    /** Working directory; defaults to the config file's directory. */
+    readonly cwd?: string;
+    /** Extra environment; values may use `${port}` / `${port:other}`. */
+    readonly env?: {
+        readonly [key: string]: string;
+    };
+    /** Spawn on startup. Defaults to true. */
+    readonly autostart?: boolean;
+    /** URL this process serves, shown in the UI as a link. */
+    readonly url?: string;
+    /** Ids of procs that must be ready before this one spawns. */
+    readonly needs?: ReadonlyArray<string>;
+    /** What "ready" means for dependents. Defaults to "listening". */
+    readonly readyWhen?: "listening" | "started";
+    readonly preflight?: Preflight;
+    readonly alerts?: ReadonlyArray<Alert>;
+};
+/** A procdeck deck: the web UI's settings and the processes it supervises. */
+export type ProcdeckConfig = {
+    /** Only meaningful in a JSON config; accepted here for symmetry. */
+    readonly $schema?: string;
+    /** Deck name; defaults to the config directory's basename. */
+    readonly name?: string;
+    /** Port for the web UI and the `*.localhost` proxy. Defaults to 4820. */
+    readonly port?: number;
+    readonly procs: ReadonlyArray<ProcSpec>;
+};
+/** Identity helper that gives config files their types. */
+export declare const defineConfig: (config: ProcdeckConfig) => ProcdeckConfig;

package/dist/public.js

@@ -0,0 +1,7 @@
+import "./chunk-MLKGABMK.js";
+
+// src/public.ts
+var defineConfig = (config) => config;
+export {
+  defineConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procdeck",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Interactive dev-process multiplexer with a web UI: terminal panes in a browser tab, declarative dependencies, assigned ports and a *.localhost reverse proxy.",
   "keywords": [
     "cli",
@@ -26,10 +26,11 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.18"
+    "node": ">=22"
   },
   "files": [
     "dist",
+    "schema.json",
     "ui/dist"
   ],
   "bin": {
@@ -37,19 +38,19 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/config.d.ts",
-      "import": "./dist/config.js"
+      "types": "./dist/public.d.ts",
+      "import": "./dist/public.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.106",
-    "node-pty": "^1.1.0"
+    "@lydell/node-pty": "1.2.0-beta.15"
   },
   "devDependencies": {
     "@effect/platform-browser": "4.0.0-beta.106",
+    "effect": "4.0.0-beta.106",
     "@types/node": "^22.10.1",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-search": "^0.16.0",
@@ -62,8 +63,9 @@
   },
   "scripts": {
     "ui:dev": "vite ui",
-    "build": "pnpm run build:meta && pnpm run build:ui && pnpm run build:js && pnpm run build:types",
+    "build": "pnpm run build:meta && pnpm run build:schema && pnpm run build:ui && pnpm run build:js && pnpm run build:types",
     "build:meta": "cp ../../readme.md ../../license .",
+    "build:schema": "node scripts/gen-schema.ts",
     "build:ui": "vite build ui",
     "build:js": "tsup",
     "build:types": "tsc -p tsconfig.build.json",

package/readme.md

@@ -56,22 +56,22 @@ which port is which**.
 
 ## Install
 
+Nothing to install, if you don't want to — write a `procdeck.config.json` (see
+[Config](#config)) and run:
+
 ```sh
-pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
+npx procdeck                      # picks up ./procdeck.config.json
+npx procdeck decks/backend.json   # or point it at any config file
 ```
 
-Requires **Node ≥ 22.18**: `procdeck.config.ts` is a TypeScript file, loaded through
-Node's built-in type stripping.
+Open <http://localhost:4820> for the panes. Requires **Node ≥ 22**.
 
-Write a `procdeck.config.ts` next to your `package.json` (see [Config](#config)), then:
+Or add it to the project, which is what you want if you keep the config in TypeScript:
 
 ```sh
-npx procdeck                    # defaults to ./procdeck.config.ts
-npx procdeck decks/backend.ts   # or point it at any config file
+pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
 ```
 
-Open <http://localhost:4820> for the panes.
-
 ## Try the example
 
 In a clone of this repo:
@@ -81,14 +81,12 @@ pnpm install
 pnpm dev          # builds the UI, starts the example stack
 ```
 
-> **Native dependency note.** procdeck runs panes through [node-pty](https://github.com/microsoft/node-pty),
-> which ships a native prebuild. npm and yarn set it up automatically. pnpm ≥ 10 and Bun
-> block dependency install scripts by default — in your own project run
-> `pnpm approve-builds` and allow `node-pty` (Bun: add it to `trustedDependencies`).
-> procdeck also repairs the most common fallout by itself at startup (the darwin
-> `spawn-helper` prebuild arriving without its execute bit), so approving is only
-> strictly required when node-pty must compile from source (no prebuild for your
-> platform).
+> **Install footprint.** ~1.8 MB, one dependency. The server is shipped as a bundle, so
+> nothing but the PTY bindings is installed — and those are
+> [`@lydell/node-pty`](https://github.com/lydell/node-pty): the same sources as
+> [node-pty](https://github.com/microsoft/node-pty), distributed as per-platform packages.
+> Nothing compiles and no install script runs, so there is no `pnpm approve-builds` /
+> `trustedDependencies` detour, and no compiler is needed on Linux.
 
 Open <http://localhost:4820> for the panes, then <http://web.localhost:4820> and
 <http://api.localhost:4820> — the example's two servers found each other (and their own
@@ -96,7 +94,31 @@ ports) entirely through `${port}` templates. See [`example/`](example/).
 
 ## Config
 
-`procdeck.config.ts` — a TypeScript file, validated by an Effect schema:
+Two formats, one schema. **JSON** needs nothing from your toolchain — no TypeScript, and
+procdeck itself doesn't have to be a dependency. Point `$schema` at the published schema
+and the editor completes and validates every field:
+
+```jsonc
+{
+  "$schema": "https://unpkg.com/procdeck/schema.json",
+  "port": 4820,
+  "procs": [
+    { "id": "api", "shell": "pnpm --filter api dev", "env": { "PORT": "${port}" } },
+    {
+      "id": "web",
+      "shell": "pnpm --filter web dev",
+      "env": { "PORT": "${port}", "API_URL": "http://localhost:${port:api}" },
+      "needs": ["api"]
+    }
+  ]
+}
+```
+
+(Installed locally, `"./node_modules/procdeck/schema.json"` works too and needs no
+network.)
+
+**TypeScript** buys comments and computed configs, at the price of Node ≥ 22.18 (native
+type stripping) and procdeck in your dependencies:
 
 ```ts
 import { defineConfig } from "procdeck"
@@ -131,7 +153,9 @@ export default defineConfig({
 ```
 
 Full field reference: [`packages/procdeck/src/config.ts`](packages/procdeck/src/config.ts)
-(the schema is the documentation).
+(the schema is the documentation — `schema.json` is generated from it at build time, so
+the two formats validate identically). Config files are looked up in this order when no
+path is given: `procdeck.config.json`, `.ts`, `.js`, `.mjs`.
 
 Tips:
 

package/schema.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/procdeck/schema.json",
+  "title": "procdeck config",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of the procdeck JSON schema, for editor completion and validation.",
+      "examples": [
+        "https://unpkg.com/procdeck/schema.json"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Deck name — the tab title and the name of the installed web app. Defaults to the config directory's basename.",
+      "examples": [
+        "my-app"
+      ]
+    },
+    "port": {
+      "description": "Port for the web UI and the `*.localhost` proxy. Defaults to 4820.",
+      "examples": [
+        4820
+      ],
+      "type": "integer",
+      "allOf": [
+        {
+          "minimum": 1,
+          "maximum": 65535
+        }
+      ]
+    },
+    "procs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable identifier: the pane label, and the proxy subdomain (`api` → http://api.localhost:4820).",
+            "examples": [
+              "api",
+              "web"
+            ],
+            "allOf": [
+              {
+                "minLength": 1
+              }
+            ]
+          },
+          "shell": {
+            "type": "string",
+            "description": "Command line handed to `$SHELL -c` — pipes, `&&` and globs work. Exactly one of `shell` or `cmd` must be set.",
+            "examples": [
+              "pnpm --filter api dev"
+            ]
+          },
+          "cmd": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "argv, executed directly without a shell. Exactly one of `shell` or `cmd` must be set.",
+            "examples": [
+              [
+                "node",
+                "server.js"
+              ]
+            ],
+            "allOf": [
+              {
+                "minItems": 1
+              }
+            ]
+          },
+          "cwd": {
+            "type": "string",
+            "description": "Working directory; defaults to the config file's directory.",
+            "examples": [
+              "packages/api"
+            ]
+          },
+          "env": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Extra environment on top of the inherited one. Values may use `${port}` / `${port:other}` templates.",
+            "examples": [
+              {
+                "PORT": "${port}",
+                "API_URL": "http://localhost:${port:api}"
+              }
+            ]
+          },
+          "autostart": {
+            "type": "boolean",
+            "description": "Spawn on startup. Defaults to true; false leaves the pane idle until Start."
+          },
+          "url": {
+            "type": "string",
+            "description": "URL this process serves, shown in the UI as a link. Also pins readiness to that URL's port.",
+            "examples": [
+              "http://localhost:${port}"
+            ]
+          },
+          "needs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Ids of procs that must be ready before this one spawns. Declarative: readiness is auto-detected, no port numbers in the config.",
+            "examples": [
+              [
+                "api"
+              ]
+            ]
+          },
+          "readyWhen": {
+            "type": "string",
+            "enum": [
+              "listening",
+              "started"
+            ],
+            "description": "What \"ready\" means for dependents: \"listening\" (default) — the process tree opened a TCP port; \"started\" — it merely spawned, for procs that never listen."
+          },
+          "preflight": {
+            "type": "object",
+            "properties": {
+              "shell": {
+                "type": "string",
+                "description": "Shell command; exit 0 lets the proc spawn.",
+                "examples": [
+                  "wrangler whoami"
+                ],
+                "allOf": [
+                  {
+                    "minLength": 1
+                  }
+                ]
+              },
+              "expect": {
+                "type": "string",
+                "description": "Regex the check's output must also match. For checks that exit 0 either way — `wrangler whoami` reports \"not authenticated\" with exit 0 — so the config needs no `| grep` pipelines.",
+                "examples": [
+                  "You are logged in"
+                ]
+              },
+              "hint": {
+                "type": "string",
+                "description": "What the human should do when the check fails; shown on the blocked pane.",
+                "examples": [
+                  "run `wrangler login`, then Start"
+                ]
+              }
+            },
+            "required": [
+              "shell"
+            ],
+            "additionalProperties": false,
+            "description": "A gate that must pass before the process spawns — e.g. `wrangler whoami` before a proc whose tree needs a Cloudflare token. Keeps interactive auth flows out of supervised panes, where a restart would kill their callback servers mid-handshake."
+          },
+          "alerts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "pattern": {
+                  "type": "string",
+                  "description": "Regex matched against a rolling tail of the pane's output.",
+                  "examples": [
+                    "ERROR",
+                    "not authenticated"
+                  ]
+                },
+                "label": {
+                  "type": "string",
+                  "description": "Badge text shown in the UI when the pattern matches.",
+                  "examples": [
+                    "needs login"
+                  ],
+                  "allOf": [
+                    {
+                      "minLength": 1
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "pattern",
+                "label"
+              ],
+              "additionalProperties": false,
+              "description": "A regex watched in the pane output; a match raises a badge in the UI."
+            },
+            "description": "Output patterns that raise a badge when they appear in the pane."
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      },
+      "description": "The processes this deck supervises."
+    }
+  },
+  "required": [
+    "procs"
+  ],
+  "additionalProperties": false
+}

package/dist/chunk-SBVZ6G4G.js

@@ -1,187 +0,0 @@
-// src/config.ts
-import { pathToFileURL } from "url";
-import * as path from "path";
-import { Effect, Schema } from "effect";
-var regexSource = Schema.String.pipe(
-  Schema.check(
-    Schema.makeFilter((pattern) => {
-      try {
-        new RegExp(pattern);
-        return void 0;
-      } catch {
-        return "expected a valid regular expression";
-      }
-    })
-  )
-);
-var PreflightSchema = Schema.Struct({
-  /** Shell command; exit 0 lets the proc spawn. */
-  shell: Schema.String.pipe(Schema.check(Schema.isMinLength(1))),
-  /**
-   * Regex that must also match the check's output. For checks that exit 0
-   * either way — `wrangler whoami` reports "not authenticated" with exit 0 —
-   * so the config doesn't need `| grep` pipelines.
-   */
-  expect: Schema.optionalKey(regexSource),
-  /** What the human should do when the check fails. */
-  hint: Schema.optionalKey(Schema.String)
-});
-var AlertSchema = Schema.Struct({
-  pattern: regexSource,
-  /** Badge text. */
-  label: Schema.String.pipe(Schema.check(Schema.isMinLength(1)))
-});
-var ProcSpecSchema = Schema.Struct({
-  /** Stable identifier, also the tab label. */
-  id: Schema.String.pipe(Schema.check(Schema.isMinLength(1))),
-  /** Command line handed to `$SHELL -c`. */
-  shell: Schema.optionalKey(Schema.String),
-  /** argv, executed without a shell. */
-  cmd: Schema.optionalKey(Schema.Array(Schema.String).pipe(Schema.check(Schema.isMinLength(1)))),
-  /** Working directory; defaults to the config file's directory. */
-  cwd: Schema.optionalKey(Schema.String),
-  /** Extra environment on top of the inherited one. */
-  env: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
-  /** Spawn on startup. Defaults to true. */
-  autostart: Schema.optionalKey(Schema.Boolean),
-  /** URL this process serves, shown in the UI as a link. */
-  url: Schema.optionalKey(Schema.String),
-  /**
-   * Names of procs that must be ready before this one spawns. Declarative:
-   * readiness is auto-detected, no port numbers in the config.
-   */
-  needs: Schema.optionalKey(Schema.Array(Schema.String)),
-  /**
-   * What "ready" means for dependents: "listening" (default) — the process
-   * tree opened a TCP port; "started" — it merely spawned (for procs that
-   * never listen).
-   */
-  readyWhen: Schema.optionalKey(Schema.Literals(["listening", "started"])),
-  /** Check that must pass before this proc spawns; failure shows as "blocked". */
-  preflight: Schema.optionalKey(PreflightSchema),
-  /** Output patterns that raise a badge when they appear in the pane. */
-  alerts: Schema.optionalKey(Schema.Array(AlertSchema))
-}).pipe(
-  Schema.check(
-    Schema.makeFilter(
-      (spec) => spec.shell === void 0 === (spec.cmd === void 0) ? "expected exactly one of `shell` or `cmd`" : void 0
-    )
-  )
-);
-var DEFAULT_UI_PORT = 4820;
-var PORT_TEMPLATE = /\$\{port(?::([^}]+))?\}/g;
-var templatedStrings = (spec) => [spec.shell, ...spec.cmd ?? [], ...Object.values(spec.env ?? {}), spec.url].filter(
-  (text) => text !== void 0
-);
-var usesOwnPort = (spec) => templatedStrings(spec).some(
-  (text) => [...text.matchAll(PORT_TEMPLATE)].some((match) => match[1] === void 0)
-);
-var portRefs = (spec) => templatedStrings(spec).flatMap(
-  (text) => [...text.matchAll(PORT_TEMPLATE)].flatMap((match) => match[1] === void 0 ? [] : [match[1]])
-);
-var resolveSpec = (spec, assigned) => {
-  const sub = (text) => text.replace(PORT_TEMPLATE, (whole, ref) => {
-    const port = assigned.get(ref ?? spec.id);
-    return port === void 0 ? whole : String(port);
-  });
-  return {
-    ...spec,
-    ...spec.shell === void 0 ? {} : { shell: sub(spec.shell) },
-    ...spec.cmd === void 0 ? {} : { cmd: spec.cmd.map(sub) },
-    ...spec.env === void 0 ? {} : { env: Object.fromEntries(Object.entries(spec.env).map(([key, value]) => [key, sub(value)])) },
-    ...spec.url === void 0 ? {} : { url: sub(spec.url) }
-  };
-};
-var validateGraph = (procs) => {
-  const ids = new Set(procs.map((proc) => proc.id));
-  if (ids.size !== procs.length) return "duplicate proc ids";
-  for (const proc of procs) {
-    for (const need of proc.needs ?? []) {
-      if (!ids.has(need)) return `proc "${proc.id}" needs unknown proc "${need}"`;
-    }
-  }
-  const needsOf = new Map(procs.map((proc) => [proc.id, proc.needs ?? []]));
-  const done = /* @__PURE__ */ new Set();
-  const onPath = /* @__PURE__ */ new Set();
-  const visit = (id) => {
-    if (done.has(id)) return void 0;
-    if (onPath.has(id)) return `dependency cycle through "${id}"`;
-    onPath.add(id);
-    for (const need of needsOf.get(id) ?? []) {
-      const cycle = visit(need);
-      if (cycle !== void 0) return cycle;
-    }
-    onPath.delete(id);
-    done.add(id);
-    return void 0;
-  };
-  for (const proc of procs) {
-    const cycle = visit(proc.id);
-    if (cycle !== void 0) return cycle;
-  }
-  return void 0;
-};
-var validatePortTemplates = (procs) => {
-  const byId = new Map(procs.map((proc) => [proc.id, proc]));
-  for (const proc of procs) {
-    for (const ref of portRefs(proc)) {
-      const target = byId.get(ref);
-      if (target === void 0) {
-        return `proc "${proc.id}" references \${port:${ref}} but there is no proc "${ref}"`;
-      }
-      if (!usesOwnPort(target)) {
-        return `proc "${proc.id}" references \${port:${ref}} but "${ref}" does not use \${port} itself`;
-      }
-    }
-  }
-  return void 0;
-};
-var ProcdeckConfigSchema = Schema.Struct({
-  /**
-   * Deck name — the tab title and the name of the installed web app.
-   * Defaults to the config directory's basename.
-   */
-  name: Schema.optionalKey(Schema.String),
-  /** Port for the web UI. Defaults to 4820. */
-  port: Schema.optionalKey(Schema.Number),
-  procs: Schema.Array(ProcSpecSchema)
-}).pipe(
-  Schema.check(
-    Schema.makeFilter(
-      (config) => validateGraph(config.procs) ?? validatePortTemplates(config.procs)
-    )
-  )
-);
-var defineConfig = (config) => config;
-var ConfigError = class extends Schema.TaggedError()("ConfigError", {
-  file: Schema.String,
-  message: Schema.String
-}) {
-};
-var loadConfig = Effect.fn("procdeck.loadConfig")(function* (file) {
-  const absolute = path.resolve(file);
-  const module = yield* Effect.tryPromise({
-    try: () => import(pathToFileURL(absolute).href),
-    catch: (cause) => new ConfigError({ file: absolute, message: String(cause) })
-  });
-  const config = yield* Effect.try({
-    try: () => Schema.decodeUnknownSync(ProcdeckConfigSchema)(module.default),
-    catch: (cause) => new ConfigError({ file: absolute, message: String(cause) })
-  });
-  const root = path.dirname(absolute);
-  const loaded = { config, root, name: config.name ?? path.basename(root) };
-  return loaded;
-});
-
-export {
-  PreflightSchema,
-  AlertSchema,
-  ProcSpecSchema,
-  DEFAULT_UI_PORT,
-  usesOwnPort,
-  resolveSpec,
-  ProcdeckConfigSchema,
-  defineConfig,
-  ConfigError,
-  loadConfig
-};