procdeck 0.1.0 → 0.2.0

package/dist/chunk-LHJTDX2F.js

@@ -0,0 +1,266 @@
+// src/config.ts
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { pathToFileURL } from "url";
+import * as path from "path";
+import { Effect, Schema } from "effect";
+var isRegex = Schema.makeFilter((pattern) => {
+  try {
+    new RegExp(pattern);
+    return void 0;
+  } catch {
+    return "expected a valid regular expression";
+  }
+});
+var regexSource = (annotations) => Schema.String.annotate(annotations).pipe(Schema.check(isRegex));
+var PreflightSchema = Schema.Struct({
+  shell: Schema.String.annotate({
+    description: "Shell command; exit 0 lets the proc spawn.",
+    examples: ["wrangler whoami"]
+  }).pipe(Schema.check(Schema.isMinLength(1))),
+  expect: Schema.optionalKey(
+    regexSource({
+      description: 'Regex the check\'s output must also match. For checks that exit 0 either way \u2014 `wrangler whoami` reports "not authenticated" with exit 0 \u2014 so the config needs no `| grep` pipelines.',
+      examples: ["You are logged in"]
+    })
+  ),
+  hint: Schema.optionalKey(
+    Schema.String.annotate({
+      description: "What the human should do when the check fails; shown on the blocked pane.",
+      examples: ["run `wrangler login`, then Start"]
+    })
+  )
+}).annotate({
+  description: "A gate that must pass before the process spawns \u2014 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."
+});
+var AlertSchema = Schema.Struct({
+  pattern: regexSource({
+    description: "Regex matched against a rolling tail of the pane's output.",
+    examples: ["ERROR", "not authenticated"]
+  }),
+  label: Schema.String.annotate({
+    description: "Badge text shown in the UI when the pattern matches.",
+    examples: ["needs login"]
+  }).pipe(Schema.check(Schema.isMinLength(1)))
+}).annotate({
+  description: "A regex watched in the pane output; a match raises a badge in the UI."
+});
+var ProcSpecSchema = Schema.Struct({
+  id: Schema.String.annotate({
+    description: "Stable identifier: the pane label, and the proxy subdomain (`api` \u2192 http://api.localhost:4820).",
+    examples: ["api", "web"]
+  }).pipe(Schema.check(Schema.isMinLength(1))),
+  shell: Schema.optionalKey(
+    Schema.String.annotate({
+      description: "Command line handed to `$SHELL -c` \u2014 pipes, `&&` and globs work. Exactly one of `shell` or `cmd` must be set.",
+      examples: ["pnpm --filter api dev"]
+    })
+  ),
+  cmd: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "argv, executed directly without a shell. Exactly one of `shell` or `cmd` must be set.",
+      examples: [["node", "server.js"]]
+    }).pipe(Schema.check(Schema.isMinLength(1)))
+  ),
+  cwd: Schema.optionalKey(
+    Schema.String.annotate({
+      description: "Working directory; defaults to the config file's directory.",
+      examples: ["packages/api"]
+    })
+  ),
+  env: Schema.optionalKey(
+    Schema.Record(Schema.String, Schema.String).annotate({
+      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: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Spawn on startup. Defaults to true; false leaves the pane idle until Start."
+    })
+  ),
+  url: Schema.optionalKey(
+    Schema.String.annotate({
+      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: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      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: Schema.optionalKey(
+    Schema.Literals(["listening", "started"]).annotate({
+      description: 'What "ready" means for dependents: "listening" (default) \u2014 the process tree opened a TCP port; "started" \u2014 it merely spawned, for procs that never listen.'
+    })
+  ),
+  preflight: Schema.optionalKey(PreflightSchema),
+  alerts: Schema.optionalKey(
+    Schema.Array(AlertSchema).annotate({
+      description: "Output patterns that raise a badge when they appear in the pane."
+    })
+  )
+}).pipe(
+  Schema.check(
+    Schema.makeFilter(
+      (spec) => spec.shell === void 0 === (spec.cmd === void 0) ? "expected exactly one of `shell` or `cmd`" : void 0
+    )
+  )
+).annotate({
+  description: "A single supervised process. Exactly one of `shell` / `cmd` is used: `shell` goes through `sh -c` (pipes, `&&`, globs work, at the cost of one extra process in the tree), `cmd` is an argv array executed directly."
+});
+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({
+  // JSON configs point at the published schema for editor completion; the key
+  // is meaningless at runtime but must be accepted, because Struct is exact.
+  $schema: Schema.optionalKey(
+    Schema.String.annotate({
+      description: "URL of the procdeck JSON schema, for editor completion and validation.",
+      examples: ["https://unpkg.com/procdeck/schema.json"]
+    })
+  ),
+  name: Schema.optionalKey(
+    Schema.String.annotate({
+      description: "Deck name \u2014 the tab title and the name of the installed web app. Defaults to the config directory's basename.",
+      examples: ["my-app"]
+    })
+  ),
+  port: Schema.optionalKey(
+    Schema.Number.annotate({
+      description: "Port for the web UI and the `*.localhost` proxy. Defaults to 4820.",
+      examples: [4820]
+    }).pipe(Schema.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 65535 })))
+  ),
+  procs: Schema.Array(ProcSpecSchema).annotate({
+    description: "The processes this deck supervises."
+  })
+}).pipe(
+  Schema.check(
+    Schema.makeFilter(
+      (config) => validateGraph(config.procs) ?? validatePortTemplates(config.procs)
+    )
+  )
+).annotate({
+  description: "A procdeck deck: the web UI's settings and the processes it supervises."
+});
+var defineConfig = (config) => config;
+var ConfigError = class extends Schema.TaggedError()("ConfigError", {
+  file: Schema.String,
+  message: Schema.String
+}) {
+};
+var CONFIG_FILENAMES = [
+  "procdeck.config.json",
+  "procdeck.config.ts",
+  "procdeck.config.js",
+  "procdeck.config.mjs"
+];
+var discoverConfig = (dir) => CONFIG_FILENAMES.map((name) => path.join(dir, name)).find((candidate) => existsSync(candidate));
+var readSource = async (absolute) => {
+  if (path.extname(absolute) === ".json") {
+    return JSON.parse(await readFile(absolute, "utf8"));
+  }
+  const module = await import(pathToFileURL(absolute).href);
+  return module.default;
+};
+var loadConfig = Effect.fn("procdeck.loadConfig")(function* (file) {
+  const absolute = path.resolve(file);
+  if (!existsSync(absolute)) {
+    return yield* new ConfigError({ file: absolute, message: "config file not found" });
+  }
+  const source = yield* Effect.tryPromise({
+    try: () => readSource(absolute),
+    catch: (cause) => new ConfigError({ file: absolute, message: String(cause) })
+  });
+  const config = yield* Effect.try({
+    try: () => Schema.decodeUnknownSync(ProcdeckConfigSchema)(source),
+    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,
+  CONFIG_FILENAMES,
+  discoverConfig,
+  loadConfig
+};

package/dist/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import {
+  CONFIG_FILENAMES,
   DEFAULT_UI_PORT,
+  discoverConfig,
   loadConfig,
   resolveSpec,
   usesOwnPort
-} from "./chunk-SBVZ6G4G.js";
+} from "./chunk-LHJTDX2F.js";
 
 // src/cli.ts
 import { Effect as Effect3, Fiber as Fiber2 } from "effect";
@@ -657,7 +659,11 @@ var serve = (supervisor, port, deck) => Effect2.acquireRelease(
 ).pipe(Effect2.as(port));
 
 // src/cli.ts
-var configPath = process.argv[2] ?? "procdeck.config.ts";
+var configPath = process.argv[2] ?? discoverConfig(process.cwd());
+if (configPath === void 0) {
+  console.error(`procdeck: no config file here \u2014 expected one of ${CONFIG_FILENAMES.join(", ")}`);
+  process.exit(1);
+}
 var main = Effect3.gen(function* () {
   const loaded = yield* loadConfig(configPath);
   const supervisor = yield* makeSupervisor(loaded);

package/dist/config.d.ts

@@ -1,67 +1,32 @@
 import { Effect, Schema } from "effect";
 export declare const PreflightSchema: Schema.Struct<{
-    /** Shell command; exit 0 lets the proc spawn. */
     readonly shell: Schema.String;
-    /**
-     * 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.
-     */
     readonly expect: Schema.optionalKey<Schema.String>;
-    /** What the human should do when the check fails. */
     readonly hint: Schema.optionalKey<Schema.String>;
 }>;
 export type Preflight = typeof PreflightSchema.Type;
-/** A regex watched in the pane output; a match raises a badge in the UI. */
 export declare const AlertSchema: Schema.Struct<{
     readonly pattern: Schema.String;
-    /** Badge text. */
     readonly label: Schema.String;
 }>;
 export type Alert = typeof AlertSchema.Type;
 export declare const ProcSpecSchema: Schema.Struct<{
-    /** Stable identifier, also the tab label. */
     readonly id: Schema.String;
-    /** Command line handed to `$SHELL -c`. */
     readonly shell: Schema.optionalKey<Schema.String>;
-    /** argv, executed without a shell. */
     readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    /** Working directory; defaults to the config file's directory. */
     readonly cwd: Schema.optionalKey<Schema.String>;
-    /** Extra environment on top of the inherited one. */
     readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
-    /** Spawn on startup. Defaults to true. */
     readonly autostart: Schema.optionalKey<Schema.Boolean>;
-    /** URL this process serves, shown in the UI as a link. */
     readonly 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.
-     */
     readonly 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).
-     */
     readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
-    /** Check that must pass before this proc spawns; failure shows as "blocked". */
     readonly preflight: Schema.optionalKey<Schema.Struct<{
-        /** Shell command; exit 0 lets the proc spawn. */
         readonly shell: Schema.String;
-        /**
-         * 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.
-         */
         readonly expect: Schema.optionalKey<Schema.String>;
-        /** What the human should do when the check fails. */
         readonly hint: Schema.optionalKey<Schema.String>;
     }>>;
-    /** Output patterns that raise a badge when they appear in the pane. */
     readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
         readonly pattern: Schema.String;
-        /** Badge text. */
         readonly label: Schema.String;
     }>>>;
 }>;
@@ -73,56 +38,26 @@ export declare const usesOwnPort: (spec: ProcSpec) => boolean;
 /** Substitute `${port}` / `${port:id}` with the ports assigned at startup. */
 export declare const resolveSpec: (spec: ProcSpec, assigned: Map<string, number>) => ProcSpec;
 export declare const ProcdeckConfigSchema: Schema.Struct<{
-    /**
-     * Deck name — the tab title and the name of the installed web app.
-     * Defaults to the config directory's basename.
-     */
+    readonly $schema: Schema.optionalKey<Schema.String>;
     readonly name: Schema.optionalKey<Schema.String>;
-    /** Port for the web UI. Defaults to 4820. */
     readonly port: Schema.optionalKey<Schema.Number>;
     readonly procs: Schema.$Array<Schema.Struct<{
-        /** Stable identifier, also the tab label. */
         readonly id: Schema.String;
-        /** Command line handed to `$SHELL -c`. */
         readonly shell: Schema.optionalKey<Schema.String>;
-        /** argv, executed without a shell. */
         readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
-        /** Working directory; defaults to the config file's directory. */
         readonly cwd: Schema.optionalKey<Schema.String>;
-        /** Extra environment on top of the inherited one. */
         readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
-        /** Spawn on startup. Defaults to true. */
         readonly autostart: Schema.optionalKey<Schema.Boolean>;
-        /** URL this process serves, shown in the UI as a link. */
         readonly 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.
-         */
         readonly 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).
-         */
         readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
-        /** Check that must pass before this proc spawns; failure shows as "blocked". */
         readonly preflight: Schema.optionalKey<Schema.Struct<{
-            /** Shell command; exit 0 lets the proc spawn. */
             readonly shell: Schema.String;
-            /**
-             * 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.
-             */
             readonly expect: Schema.optionalKey<Schema.String>;
-            /** What the human should do when the check fails. */
             readonly hint: Schema.optionalKey<Schema.String>;
         }>>;
-        /** Output patterns that raise a badge when they appear in the pane. */
         readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
             readonly pattern: Schema.String;
-            /** Badge text. */
             readonly label: Schema.String;
         }>>>;
     }>>;
@@ -143,5 +78,13 @@ declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"C
 }>, import("effect/Cause").YieldableError>;
 export declare class ConfigError extends ConfigError_base {
 }
+/**
+ * Config file names the CLI looks for when started without an argument, in
+ * order. JSON comes first because it needs nothing from the toolchain: no
+ * TypeScript, and no procdeck in the project's dependencies.
+ */
+export declare const CONFIG_FILENAMES: readonly ["procdeck.config.json", "procdeck.config.ts", "procdeck.config.js", "procdeck.config.mjs"];
+/** The first config file present in `dir`, if any. */
+export declare const discoverConfig: (dir: string) => string | undefined;
 export declare const loadConfig: (file: string) => Effect.Effect<LoadedConfig, ConfigError, never>;
 export {};

package/dist/config.js

@@ -1,23 +1,27 @@
 import {
   AlertSchema,
+  CONFIG_FILENAMES,
   ConfigError,
   DEFAULT_UI_PORT,
   PreflightSchema,
   ProcSpecSchema,
   ProcdeckConfigSchema,
   defineConfig,
+  discoverConfig,
   loadConfig,
   resolveSpec,
   usesOwnPort
-} from "./chunk-SBVZ6G4G.js";
+} from "./chunk-LHJTDX2F.js";
 export {
   AlertSchema,
+  CONFIG_FILENAMES,
   ConfigError,
   DEFAULT_UI_PORT,
   PreflightSchema,
   ProcSpecSchema,
   ProcdeckConfigSchema,
   defineConfig,
+  discoverConfig,
   loadConfig,
   resolveSpec,
   usesOwnPort

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procdeck",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -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:
@@ -96,7 +96,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 +155,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
-};