dev-cockpit 0.2.2 → 0.2.4

package/dist/{link-HXNII7EU.js → link-VWT2VQH6.js}

@@ -7,7 +7,7 @@ import {
   manifestPath,
   removeMapping,
   setMapping
-} from "./chunk-C4GFJDMG.js";
+} from "./chunk-A446TCT5.js";
 import "./chunk-6XGHLLYT.js";
 
 // src/commands/link.ts
@@ -62,4 +62,4 @@ export {
   linkListCommand,
   linkRemoveCommand
 };
-//# sourceMappingURL=link-HXNII7EU.js.map
+//# sourceMappingURL=link-VWT2VQH6.js.map

package/dist/mount/overlay-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolve where the docker-compose overlay file should be written for a
+ * workspace.
+ *
+ * Default (no `mount.overlayPath` in cockpit.yaml):
+ *   <stateDir>/dev-mount-overlay.yml
+ *   — sibling to `mount.manifest.json`. Keeps the wrapper repo clean of
+ *     per-developer state; aligns the overlay's lifecycle with the
+ *     manifest's.
+ *
+ * Override (cockpit.yaml `mount.overlayPath` is set):
+ *   - Workspace-relative paths resolve against `workspaceRoot`.
+ *   - Absolute paths are honoured verbatim.
+ *
+ * Pure: no I/O. Tested in isolation.
+ */
+export interface ResolveOverlayPathOptions {
+    /** Cockpit state dir for this workspace. */
+    stateDir: string;
+    /** Workspace root, used to resolve relative `configOverride`. */
+    workspaceRoot: string;
+    /** Optional `mount.overlayPath` value from cockpit.yaml. */
+    configOverride?: string | undefined;
+}
+export declare function resolveOverlayPath(opts: ResolveOverlayPathOptions): string;
+//# sourceMappingURL=overlay-path.d.ts.map

package/dist/mount/overlay-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-path.d.ts","sourceRoot":"","sources":["../../src/mount/overlay-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,yBAAyB;IACxC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,MAAM,CAM1E"}

package/docs/config-reference.md

@@ -14,7 +14,7 @@ A `cockpit.yaml` lives at the root of your project. The cockpit reads it on star
 | `highlights` | array | no | Regex patterns applied to all output streams (process + docker). Each can carry an explicit `severity:` (else inferred). |
 | `health` | array | no | Health check declarations — see `health:` below. |
 | `actions` | array | no | Named, optionally key-bound shell commands surfaced via the `:` palette and the Targets pane. |
-| `mount` | object | no | `overlayPath`, `manifestFile` overrides. Defaults: `docker-compose.dev-cockpit.yml`, `mount.manifest.json`. |
+| `mount` | object | no | `overlayPath`, `manifestFile` overrides. Defaults: `<stateDir>/dev-mount-overlay.yml` (sibling to the manifest, keeps the wrapper repo clean), `mount.manifest.json`. |
 | `mounts` | array | no | Explicit `{hostPath, containerPath, meta?}` entries for `dev-cockpit mount`. |
 | `help` | object | no | Extra `sources[]` + `defaultPage`. |
 | `notifications` | object | no | `enabled`, `onTransitionTo[]`, `exclude[]`. |
@@ -84,8 +84,9 @@ health:
 ## `mount:` + `mounts:`
 
 ```yaml
-mount:                                                # path overrides
-  overlayPath: docker-compose.dev-cockpit.yml         # workspace-relative
+mount:                                                # path overrides — omit for defaults
+  # overlayPath: docker-compose.dev-cockpit.yml       # default: <stateDir>/dev-mount-overlay.yml
+                                                      #   set to keep the overlay in-repo (workspace-relative or absolute)
   manifestFile: mount.manifest.json                   # basename within stateDir
 
 mounts:                                               # explicit candidates

package/docs/mount.md

@@ -26,22 +26,22 @@ dev-cockpit mount status         # active mounts with branch / dirty / broken-sy
 dev-cockpit mount clear          # remove overlay + manifest + symlinks
 ```
 
-Apply the generated overlay alongside your existing compose file:
+Apply the generated overlay alongside your existing compose file (the path is printed by `dev-cockpit mount` — copy it from there):
 
 ```sh
-docker compose -f docker-compose.yml -f docker-compose.dev-cockpit.yml up -d
+docker compose -f docker-compose.yml -f <stateDir>/dev-mount-overlay.yml up -d
 ```
 
 ## What gets written
 
 | File | Default path | Configurable via |
 |---|---|---|
-| Compose overlay | `<workspace>/docker-compose.dev-cockpit.yml` | `config.mount.overlayPath` |
+| Compose overlay | `<stateDir>/dev-mount-overlay.yml` | `config.mount.overlayPath` |
 | Manifest | `<stateDir>/mount.manifest.json` | `config.mount.manifestFile` |
 
-`<stateDir>` lives under `$XDG_STATE_HOME/<appName>/<workspace-hash>/`. The manifest tracks what was applied and when, and is the source of truth for `status` and `clear`.
+`<stateDir>` lives under `$XDG_STATE_HOME/<appName>/<workspace-hash>/`. Both files share that location, so anything cockpit knows about *this workspace's mounts* sits in one dir — clean wrapper repo, no per-developer artefacts to gitignore.
 
-Override the paths when the wrapper has its own conventions:
+Override the overlay path when the wrapper has its own conventions (workspace-relative or absolute):
 
 ```yaml
 mount:

package/examples/cockpit.schema.json

@@ -0,0 +1,280 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/frankfava/package--dev-cockpit/main/examples/cockpit.schema.json",
+  "title": "dev-cockpit cockpit.yaml",
+  "description": "Configuration file for dev-cockpit and profile-based cockpits. Mirrors BaseCockpitConfigSchema in src/core/config.ts — keep both in sync when adding fields.",
+  "type": "object",
+  "required": ["version", "appName"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 2,
+      "description": "Config schema version. Current: 2. Older configs (v1) are migrated in memory; run `dev-cockpit migrate-config` to persist."
+    },
+    "appName": {
+      "type": "string",
+      "description": "State-dir name under $XDG_STATE_HOME (default: ~/.local/state/<appName>/<workspace-hash>/)."
+    },
+    "processes": {
+      "type": "array",
+      "description": "Long-running commands streamed into the Output pane. Each runs once at startup and is restarted on `restartOn` fsevents.",
+      "items": { "$ref": "#/$defs/Process" }
+    },
+    "repos": {
+      "type": "array",
+      "description": "Rows shown in the Repos/Targets pane.",
+      "items": { "$ref": "#/$defs/Repo" }
+    },
+    "docker": {
+      "$ref": "#/$defs/Docker",
+      "description": "Compose log tailing + container health-check enabler. Omit for non-docker projects to hide the docker pieces entirely."
+    },
+    "highlights": {
+      "type": "array",
+      "description": "Regex patterns applied to all output streams (processes + docker). Each can carry an explicit severity; otherwise inferred.",
+      "items": { "$ref": "#/$defs/Highlight" }
+    },
+    "health": {
+      "type": "array",
+      "description": "Health-check declarations. `type` references a built-in (`container-running` | `port-open` | `http-ok` | `file-exists` | `exec-zero`) or a profile-registered check id.",
+      "items": { "$ref": "#/$defs/HealthCheck" }
+    },
+    "help": {
+      "$ref": "#/$defs/Help",
+      "description": "Extra markdown directories layered on top of the built-in help."
+    },
+    "notifications": {
+      "$ref": "#/$defs/Notifications",
+      "description": "Native OS notifications, transition-only by default."
+    },
+    "mounts": {
+      "type": "array",
+      "description": "Explicit `{hostPath, containerPath, meta?}` candidates for `dev-cockpit mount`. Merged with `profile.mountCandidatesProvider()`.",
+      "items": { "$ref": "#/$defs/Mount" }
+    },
+    "mount": {
+      "$ref": "#/$defs/MountSettings",
+      "description": "Overlay/manifest path overrides. Default overlay lives at <stateDir>/dev-mount-overlay.yml (out of the repo)."
+    },
+    "defaultPane": {
+      "type": "string",
+      "enum": ["repos", "output", "health", "help"],
+      "description": "Which pane the cockpit lands on when it boots. Profile may override; falls back to Output when the requested tab is hidden."
+    },
+    "actions": {
+      "type": "array",
+      "description": "Named, key-bound shell commands surfaced via the `:` command palette and the Targets pane.",
+      "items": { "$ref": "#/$defs/Action" }
+    },
+    "profile": {
+      "type": "object",
+      "description": "Profile-specific config namespace. Each profile owns one key under here (e.g. `profile.awc-cockpit: { gitlab: {...} }`) and validates it via its own configSchemaExt."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "NotifyOverride": {
+      "description": "Either `false` (mute notifications for this item) or `{ onTransitionTo: [...] }` to override the global transition list.",
+      "oneOf": [
+        { "type": "boolean", "const": false },
+        {
+          "type": "object",
+          "properties": {
+            "onTransitionTo": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "Process": {
+      "type": "object",
+      "required": ["id", "command"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "command": { "type": "string", "description": "Shell command. Spawned via the wrapper with the workspace as cwd by default." },
+        "cwd": { "type": "string", "description": "Workspace-relative override of the process working dir." },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } },
+        "color": { "type": "string", "description": "ANSI colour for prefixed output (cyan / magenta / yellow / blue / green / red / white)." },
+        "restartOn": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns; when a matching file changes, the process is killed + respawned."
+        },
+        "notify": { "$ref": "#/$defs/NotifyOverride" }
+      },
+      "additionalProperties": false
+    },
+    "Repo": {
+      "type": "object",
+      "required": ["id", "path"],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "Workspace-relative path to the repo root." },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "Service": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "description": "Compose service name." },
+        "tail": { "type": "boolean", "default": true }
+      },
+      "additionalProperties": false
+    },
+    "Docker": {
+      "type": "object",
+      "properties": {
+        "composeFile": {
+          "type": "string",
+          "description": "Workspace-relative path to docker-compose.yml. When unset, docker compose auto-discovers from cwd."
+        },
+        "services": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Service" },
+          "description": "Services to tail in the Output pane + reference as `container-running` health check targets."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Highlight": {
+      "type": "object",
+      "required": ["pattern"],
+      "properties": {
+        "pattern": { "type": "string", "description": "JavaScript-flavour regex." },
+        "severity": {
+          "type": "string",
+          "enum": ["info", "warn", "error"],
+          "default": "info"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Remediation": {
+      "type": "object",
+      "required": ["key", "label", "command"],
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "maxLength": 1, "description": "Single key character that triggers the remediation in the Health pane." },
+        "label": { "type": "string" },
+        "command": { "type": "string" },
+        "cwd": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "HealthCheck": {
+      "type": "object",
+      "required": ["id", "label", "type", "remediation"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "type": {
+          "type": "string",
+          "description": "Built-in: container-running | port-open | http-ok | file-exists | exec-zero. Profiles may register additional check types."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["ok", "warn", "error"],
+          "description": "Severity to report on failure (default error)."
+        },
+        "triggers": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["startup", "fsevent", "lockfile", "docker"] },
+          "description": "When to re-run this check. Sensible defaults per check type when omitted."
+        },
+        "url": { "type": "string", "description": "http-ok target." },
+        "expectStatus": { "type": "integer", "description": "http-ok success status (default 200)." },
+        "container": { "type": "string", "description": "container-running target — compose service or container name (substring match against `docker ps --filter name=`)." },
+        "port": { "type": "integer", "description": "port-open TCP port." },
+        "host": { "type": "string", "description": "port-open / http-ok host override (default 127.0.0.1)." },
+        "path": { "type": "string", "description": "file-exists path (workspace-relative)." },
+        "command": { "type": "string", "description": "exec-zero command to run (success = exit 0)." },
+        "args": { "type": "array", "items": { "type": "string" }, "description": "exec-zero argv." },
+        "cwd": { "type": "string", "description": "exec-zero cwd override." },
+        "notify": { "$ref": "#/$defs/NotifyOverride" },
+        "remediation": { "$ref": "#/$defs/Remediation" }
+      },
+      "additionalProperties": false
+    },
+    "Help": {
+      "type": "object",
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Workspace-relative paths to markdown dirs layered on top of built-in help."
+        },
+        "defaultPage": { "type": "string", "description": "Slug of the page to land on when Help opens." }
+      },
+      "additionalProperties": false
+    },
+    "Notifications": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "onTransitionTo": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Severities that fire a notification on transition (default: [error, recovered])."
+        },
+        "exclude": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Check ids to mute even when their severity matches."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Mount": {
+      "type": "object",
+      "required": ["hostPath", "containerPath"],
+      "properties": {
+        "hostPath": { "type": "string" },
+        "containerPath": { "type": "string" },
+        "meta": { "type": "object", "description": "Opaque to dev-cockpit core; consumed by profile hooks (e.g. awc reads meta.name and meta.type)." }
+      },
+      "additionalProperties": false
+    },
+    "MountSettings": {
+      "type": "object",
+      "properties": {
+        "overlayPath": {
+          "type": "string",
+          "description": "Override for the generated docker-compose overlay. Unset = <stateDir>/dev-mount-overlay.yml (recommended). Set values are workspace-relative; absolute paths honoured verbatim."
+        },
+        "manifestFile": {
+          "type": "string",
+          "default": "mount.manifest.json",
+          "description": "Basename inside stateDir for the mount manifest."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Action": {
+      "type": "object",
+      "required": ["id", "label", "command"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "command": { "type": "string", "description": "Shell command to run. cwd defaults to the workspace." },
+        "cwd": { "type": "string" },
+        "scope": {
+          "type": "string",
+          "pattern": "^(global|repos(:[\\w-]+)?)$",
+          "description": "Where the action appears: 'global' (palette only), 'repos' (every repo row), or 'repos:<id>' (a specific repo)."
+        },
+        "key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1,
+          "description": "Single key character that fires the action when the row is focused or the palette is open."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/examples/cockpit.yaml

@@ -1,11 +1,18 @@
-# cockpit.yaml — example config
+# yaml-language-server: $schema=./cockpit.schema.json
+# cockpit.yaml — example config (schema v2)
 # Run `dev-cockpit dev` from the directory containing this file.
+# Or, if it lives elsewhere:
+#   dev-cockpit link <path/to/this-file>     # registers cwd → this config
+#   dev-cockpit dev                          # picks it up via the manifest
+#   DEV_COCKPIT_CONFIG=<path> dev-cockpit dev   # one-shot env override
+#   dev-cockpit dev --config <path>          # one-shot CLI override
 
-version: 1                            # config schema version; required
-appName: my-app                       # state dir: ~/.local/state/my-app/
+version: 2                            # config schema version; required (v1 auto-migrated in memory)
+appName: my-app                       # state dir: ~/.local/state/my-app/<workspace-hash>/
 
-# Watchers — long-running commands streamed into the Output pane.
-watchers:
+# Processes — long-running commands streamed into the Output pane.
+# Renamed from `watchers` in schema v2; v1 configs still load with a one-time warning.
+processes:
   - id: typecheck
     label: tsc --watch
     command: npx tsc --watch --noEmit
@@ -18,12 +25,12 @@ watchers:
     label: eslint
     command: npx eslint . --watch
     color: yellow
-    notify: false                     # mute notifications for this watcher
+    notify: false                     # mute notifications for this process
     restartOn:
       - package.json
       - .eslintrc.*
 
-# Repos — what shows in the Repos pane (optional; default = empty).
+# Repos — rows in the Repos/Targets pane.
 repos:
   - id: api
     path: ./packages/api
@@ -33,7 +40,7 @@ repos:
     label: Web
 
 # Docker — enables container log tailing, container health checks, mount overlay.
-# Omit this whole block for plain-Node projects; the docker tab/section won't appear.
+# Omit this whole block for plain-Node projects; the docker pieces stay hidden.
 docker:
   composeFile: ./docker-compose.yml
   services:
@@ -44,7 +51,7 @@ docker:
     - name: redis
       tail: false
 
-# Highlight patterns — applied to all log streams.
+# Highlight patterns — applied to all output streams (processes + docker logs).
 highlights:
   - pattern: ERROR
     severity: error
@@ -96,7 +103,7 @@ health:
       label: run migrations
       command: npm run db:migrate
 
-# Help — extra markdown directories layered on top of core's built-in docs.
+# Help — extra markdown directories layered on top of the built-in help.
 help:
   sources:
     - ./docs
@@ -109,6 +116,25 @@ notifications:
     - error
     - recovered
 
+# Mount overlay placement (optional). Default: <stateDir>/dev-mount-overlay.yml,
+# sibling to mount.manifest.json — keeps the wrapper repo clean of per-developer
+# state. Set if you want the overlay in-repo for any reason.
+# mount:
+#   overlayPath: docker/compose/dev-mount-overlay.yml   # workspace-relative
+#   manifestFile: mount.manifest.json                   # basename inside stateDir
+
+# Actions — named, key-bound shell commands surfaced via the `:` palette and
+# the Targets pane. `scope` values: `global` | `repos` | `repos:<id>`.
+actions:
+  - id: docs
+    label: Open docs
+    command: open ./docs/index.html
+    scope: global
+    key: o
+
+# Which pane the cockpit lands on when it boots.
+defaultPane: repos                    # repos | output | health | help
+
 # Profile-specific config lives under `profile.<name>` — validated by the
 # profile's `configSchemaExt` zod extension. Generic core ignores this block.
 # profile:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dev-cockpit",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"description": "A reusable, domain-neutral terminal UI dev cockpit — tabbed pane shell, watcher streaming, optional Docker log tail with highlights, health framework with one-keystroke remediations, transition-only OS notifications, live-markdown Help. Profiles extend it with project-specific commands, repos, and health checks.",
 	"license": "MIT",
 	"repository": {