procdeck 0.2.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.2.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",
@@ -38,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",

package/readme.md

@@ -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

package/dist/chunk-LHJTDX2F.js

@@ -1,266 +0,0 @@
-// 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/config.d.ts

@@ -1,90 +0,0 @@
-import { Effect, Schema } from "effect";
-export declare const PreflightSchema: Schema.Struct<{
-    readonly shell: Schema.String;
-    readonly expect: Schema.optionalKey<Schema.String>;
-    readonly hint: Schema.optionalKey<Schema.String>;
-}>;
-export type Preflight = typeof PreflightSchema.Type;
-export declare const AlertSchema: Schema.Struct<{
-    readonly pattern: Schema.String;
-    readonly label: Schema.String;
-}>;
-export type Alert = typeof AlertSchema.Type;
-export declare const ProcSpecSchema: Schema.Struct<{
-    readonly id: Schema.String;
-    readonly shell: Schema.optionalKey<Schema.String>;
-    readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    readonly cwd: Schema.optionalKey<Schema.String>;
-    readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
-    readonly autostart: Schema.optionalKey<Schema.Boolean>;
-    readonly url: Schema.optionalKey<Schema.String>;
-    readonly needs: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
-    readonly preflight: Schema.optionalKey<Schema.Struct<{
-        readonly shell: Schema.String;
-        readonly expect: Schema.optionalKey<Schema.String>;
-        readonly hint: Schema.optionalKey<Schema.String>;
-    }>>;
-    readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
-        readonly pattern: Schema.String;
-        readonly label: Schema.String;
-    }>>>;
-}>;
-export type ProcSpec = typeof ProcSpecSchema.Type;
-/** Default port of the UI + proxy server. */
-export declare const DEFAULT_UI_PORT = 4820;
-/** Whether the spec asks procdeck to assign it a port (`${port}` anywhere). */
-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<{
-    readonly $schema: Schema.optionalKey<Schema.String>;
-    readonly name: Schema.optionalKey<Schema.String>;
-    readonly port: Schema.optionalKey<Schema.Number>;
-    readonly procs: Schema.$Array<Schema.Struct<{
-        readonly id: Schema.String;
-        readonly shell: Schema.optionalKey<Schema.String>;
-        readonly cmd: Schema.optionalKey<Schema.$Array<Schema.String>>;
-        readonly cwd: Schema.optionalKey<Schema.String>;
-        readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
-        readonly autostart: Schema.optionalKey<Schema.Boolean>;
-        readonly url: Schema.optionalKey<Schema.String>;
-        readonly needs: Schema.optionalKey<Schema.$Array<Schema.String>>;
-        readonly readyWhen: Schema.optionalKey<Schema.Literals<readonly ["listening", "started"]>>;
-        readonly preflight: Schema.optionalKey<Schema.Struct<{
-            readonly shell: Schema.String;
-            readonly expect: Schema.optionalKey<Schema.String>;
-            readonly hint: Schema.optionalKey<Schema.String>;
-        }>>;
-        readonly alerts: Schema.optionalKey<Schema.$Array<Schema.Struct<{
-            readonly pattern: Schema.String;
-            readonly label: Schema.String;
-        }>>>;
-    }>>;
-}>;
-export type ProcdeckConfig = typeof ProcdeckConfigSchema.Type;
-/** Identity helper that gives config files their types. */
-export declare const defineConfig: (config: ProcdeckConfig) => ProcdeckConfig;
-export type LoadedConfig = {
-    config: ProcdeckConfig;
-    /** Directory of the config file — the default cwd for every process. */
-    root: string;
-    /** `config.name`, or the root directory's basename. */
-    name: string;
-};
-declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
-    readonly file: Schema.String;
-    readonly message: Schema.String;
-}>, 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,28 +0,0 @@
-import {
-  AlertSchema,
-  CONFIG_FILENAMES,
-  ConfigError,
-  DEFAULT_UI_PORT,
-  PreflightSchema,
-  ProcSpecSchema,
-  ProcdeckConfigSchema,
-  defineConfig,
-  discoverConfig,
-  loadConfig,
-  resolveSpec,
-  usesOwnPort
-} from "./chunk-LHJTDX2F.js";
-export {
-  AlertSchema,
-  CONFIG_FILENAMES,
-  ConfigError,
-  DEFAULT_UI_PORT,
-  PreflightSchema,
-  ProcSpecSchema,
-  ProcdeckConfigSchema,
-  defineConfig,
-  discoverConfig,
-  loadConfig,
-  resolveSpec,
-  usesOwnPort
-};