@visulima/vis 1.0.0-alpha.15 → 1.0.0-alpha.17

package/dist/config/index.d.ts

@@ -1,88 +1,7 @@
-import { TaskResult, Task, TargetConfiguration, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
+import { TargetConfiguration, TaskResult, Task, FingerprintContributor, ConstraintsConfig, NamedInputs, TaskRunnerOptions } from '@visulima/task-runner';
+export { type FingerprintContributor } from '@visulima/task-runner';
 import { Hookable } from 'hookable';
 /**
-* Typed hook surface exposed to vis plugins.
-*
-* Plugins subscribe via `hooks.hook(name, handler)` — handlers are
-* awaited sequentially in registration order. Returning a promise
-* delays the next hook firing until it resolves, so plugins can
-* safely perform async setup/teardown.
-*
-* Naming deliberately mirrors vite-task / webpack-style verbs:
-*   before/after for boundaries, on<Event> for passive observation.
-*/
-interface VisHooks {
-  /**
-  * Fired after the entire task graph completes (including any
-  * failures). `results` maps task ID → {@link TaskResult}.
-  */
-  "run:after": (results: Map<string, TaskResult>) => Promise<void> | void;
-  /**
-  * Fired once before any task in the graph starts, after workspace
-  * discovery and graph construction. Throwing aborts the run.
-  */
-  "run:before": (context: {
-    tasks: Task[];
-    workspaceRoot: string;
-  }) => Promise<void> | void;
-  /**
-  * Fired after a task completes (success, failure, or cache hit).
-  * Receives the final {@link TaskResult}.
-  */
-  "task:after": (task: Task, result: TaskResult) => Promise<void> | void;
-  /**
-  * Fired before each task begins execution — after scheduling, before
-  * the executor runs the command. Throwing aborts that single task.
-  */
-  "task:before": (task: Task) => Promise<void> | void;
-  /** Fired when a task hit the local or remote cache. */
-  "task:cacheHit": (task: Task, result: TaskResult) => Promise<void> | void;
-  /**
-  * Fired when auto-fingerprint cache diagnostics reports a miss,
-  * carrying the human-readable reason string.
-  */
-  "task:cacheMiss": (task: Task, reasons: string) => Promise<void> | void;
-  /** Fired when a task exits non-zero. */
-  "task:failure": (task: Task, result: TaskResult) => Promise<void> | void;
-  /**
-  * Fired with a stderr chunk as a running task emits it. Plugins
-  * that ship logs live (Slack, Datadog) should prefer this over
-  * `task:after` so they don't wait for the full buffer.
-  */
-  "task:stderr": (task: Task, chunk: string) => Promise<void> | void;
-  /**
-  * Fired with a stdout chunk as a running task emits it. See
-  * `task:stderr` for semantics.
-  */
-  "task:stdout": (task: Task, chunk: string) => Promise<void> | void;
-}
-/**
-* Public plugin contract. Implementations register handlers by
-* returning a partial {@link VisHooks} map from `hooks`, or by
-* mutating the Hookable instance directly via `setup(hooks)` for
-* advanced cases (dynamic registration, removeHook, etc.).
-*
-* Plugins are loaded in the order they appear in `visConfig.plugins`.
-* Handler execution order within a hook follows registration order,
-* so earlier plugins see events first.
-*/
-interface VisPlugin {
-  /**
-  * Declarative handlers — the common shape. One entry per hook
-  * name; pass a function or an array of functions (all run serially
-  * in order).
-  */
-  hooks?: Partial<{ [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][] }>;
-  /** Plugin name — surfaced in debug logs. */
-  name: string;
-  /**
-  * Imperative setup — receives the shared Hookable instance so the
-  * plugin can register hooks conditionally, unregister later, or
-  * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
-  */
-  setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
-}
-/**
 * One family of upstream-coupled packages.
 *
 * `members` is an exact-match list. `prefixes` accept any dep whose
@@ -191,6 +110,40 @@ interface ServiceConfig {
   };
 }
 /**
+* Persisted registry entry. One JSON file per running service in
+* `~/.vis-services/&lt;workspaceHash>/&lt;slug>.json`.
+*/
+interface ServiceEntry {
+  /** Resolved command actually spawned. Used for stale-PID detection. */
+  command: string;
+  /** Service config captured at start time. */
+  config: ServiceConfig;
+  cwd: string;
+  /**
+  * Env vars to forward to dependents. Resolved at start time —
+  * defaults to `config.env`, but a future `--env-from` flag could
+  * extend this without touching the registry consumer.
+  */
+  env: Record<string, string>;
+  /** Target id, e.g. `apps/api:db`. */
+  id: string;
+  /** Absolute path to the captured stdout/stderr log file. */
+  logFile: string;
+  pid: number;
+  /**
+  * Filesystem-safe slug of `id`. `apps/api:db` → `apps_api__db`.
+  * Used as the entry's filename so registry reads can map slug → entry.
+  */
+  slug: string;
+  /** ISO 8601 timestamp of when the service was started. */
+  startedAt: string;
+  /**
+  * vis version that started this service. Auto-attach refuses entries
+  * from a mismatched version — protects against schema drift.
+  */
+  visVersion: string;
+}
+/**
 * Semantic classification for a target.
 * - `build`: Generates one or more artifacts; cached by default.
 * - `test`: Validation task (lint, typecheck, unit test). Default type.
@@ -437,6 +390,132 @@ interface VisTargetConfiguration extends Omit<TargetConfiguration, "options"> {
   */
   type?: TargetType;
 }
+/**
+* Typed hook surface exposed to vis plugins.
+*
+* Plugins subscribe via `hooks.hook(name, handler)` — handlers are
+* awaited sequentially in registration order. Returning a promise
+* delays the next hook firing until it resolves, so plugins can
+* safely perform async setup/teardown.
+*
+* Naming deliberately mirrors vite-task / webpack-style verbs:
+*   before/after for boundaries, on&lt;Event> for passive observation.
+*/
+interface VisHooks {
+  /**
+  * Fired after the entire task graph completes (including any
+  * failures). `results` maps task ID → {@link TaskResult}.
+  */
+  "run:after": (results: Map<string, TaskResult>) => Promise<void> | void;
+  /**
+  * Fired once before any task in the graph starts, after workspace
+  * discovery and graph construction. Throwing aborts the run.
+  */
+  "run:before": (context: {
+    tasks: Task[];
+    workspaceRoot: string;
+  }) => Promise<void> | void;
+  /**
+  * Fired after a task completes (success, failure, or cache hit).
+  * Receives the final {@link TaskResult}.
+  */
+  "task:after": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired before each task begins execution — after scheduling, before
+  * the executor runs the command. Throwing aborts that single task.
+  */
+  "task:before": (task: Task) => Promise<void> | void;
+  /** Fired when a task hit the local or remote cache. */
+  "task:cacheHit": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired when auto-fingerprint cache diagnostics reports a miss,
+  * carrying the human-readable reason string.
+  */
+  "task:cacheMiss": (task: Task, reasons: string) => Promise<void> | void;
+  /** Fired when a task exits non-zero. */
+  "task:failure": (task: Task, result: TaskResult) => Promise<void> | void;
+  /**
+  * Fired with a stderr chunk as a running task emits it. Plugins
+  * that ship logs live (Slack, Datadog) should prefer this over
+  * `task:after` so they don't wait for the full buffer.
+  */
+  "task:stderr": (task: Task, chunk: string) => Promise<void> | void;
+  /**
+  * Fired with a stdout chunk as a running task emits it. See
+  * `task:stderr` for semantics.
+  */
+  "task:stdout": (task: Task, chunk: string) => Promise<void> | void;
+  /**
+  * Fired during fingerprint construction, after built-in inputs are
+  * gathered and before the hash is sealed. Plugins call
+  * `contributor.contribute(key, value)` to mix arbitrary strings
+  * into the task hash — the hasher namespaces and sorts contributions
+  * deterministically so call order doesn't change the result.
+  *
+  * Throwing aborts hashing for the offending task and surfaces as a
+  * task failure before any cache lookup runs. Use this to guarantee
+  * a buggy plugin can't quietly poison cache state.
+  */
+  "task:fingerprint": (task: Task, contributor: FingerprintContributor) => Promise<void> | void;
+  /**
+  * Fired right before a failed task is re-spawned by the retry
+  * controller. `attempt` is 1-indexed and counts the retry that's
+  * about to start (so the original failed run was attempt 0).
+  * `prevExitCode` is the failing exit status that triggered the
+  * retry (the full TaskResult isn't materialized at the retry
+  * boundary — only the per-attempt close event is available).
+  *
+  * Throwing aborts the retry; the previous failure becomes the final
+  * result.
+  */
+  "task:retry": (task: Task, attempt: number, prevExitCode: number) => Promise<void> | void;
+  /**
+  * Fired after `vis run` auto-attaches to one or more registered
+  * services. `taskIds` lists the in-graph dependents that consumed
+  * the service's `env` block; an empty array means the service was
+  * registered but no kept task depended on it.
+  */
+  "service:attach": (entry: ServiceEntry, taskIds: ReadonlyArray<string>) => Promise<void> | void;
+  /**
+  * Fired after a service is registered and its readiness probe
+  * succeeds. Sourced from both `vis service start` (and `restart`'s
+  * post-start phase) and any future programmatic call sites.
+  */
+  "service:start": (entry: ServiceEntry) => Promise<void> | void;
+  /**
+  * Fired after a registered service is stopped (SIGTERM/SIGKILL
+  * acknowledged, registry entry deleted). Not fired when stop is
+  * called against an unknown id — only when there was an alive
+  * entry to terminate.
+  */
+  "service:stop": (entry: ServiceEntry) => Promise<void> | void;
+}
+/**
+* Public plugin contract. Implementations register handlers by
+* returning a partial {@link VisHooks} map from `hooks`, or by
+* mutating the Hookable instance directly via `setup(hooks)` for
+* advanced cases (dynamic registration, removeHook, etc.).
+*
+* Plugins are loaded in the order they appear in `visConfig.plugins`.
+* Handler execution order within a hook follows registration order,
+* so earlier plugins see events first.
+*/
+interface VisPlugin {
+  /**
+  * Declarative handlers — the common shape. One entry per hook
+  * name; pass a function or an array of functions (all run serially
+  * in order).
+  */
+  hooks?: Partial<{ [K in keyof VisHooks]: VisHooks[K] | VisHooks[K][] }>;
+  /** Plugin name — surfaced in debug logs. */
+  name: string;
+  /**
+  * Imperative setup — receives the shared Hookable instance so the
+  * plugin can register hooks conditionally, unregister later, or
+  * use advanced APIs like `hookOnce`/`beforeEach`/`afterEach`.
+  */
+  setup?: (hooks: Hookable<VisHooks>) => Promise<void> | void;
+}
 interface CodeownersConfig {
   /** Workspace-level paths that apply outside any project (e.g., `.github/**`). */
   globalPaths?: Record<string, string[]>;
@@ -521,8 +600,15 @@ interface ProjectJson {
     owner?: string;
     title?: string;
   };
-  /** Project type — library or application. */
-  projectType?: "application" | "library";
+  /**
+  * Project type — `library`, `application`, `service`, or `tool`.
+  *
+  * - `library` — reusable code consumed by other workspace projects.
+  * - `application` — end-user-facing build target (web app, mobile app).
+  * - `service` — long-running HTTP / worker process deployed independently.
+  * - `tool` — CLI or developer tooling shipped as an executable.
+  */
+  projectType?: "application" | "library" | "service" | "tool";
   /** Source root, used for display and language inference. */
   sourceRoot?: string;
   /** Tech stack. */
@@ -542,7 +628,7 @@ interface TaskDefaultsScope {
   /** Match on project layer. */
   layer?: ProjectJson["layer"] | ProjectJson["layer"][];
   /** Match on project type. */
-  projectType?: "application" | "library";
+  projectType?: "application" | "library" | "service" | "tool";
   /** Match on project stack. */
   stack?: ProjectJson["stack"] | ProjectJson["stack"][];
   /** Match projects tagged with any of these tags. */
@@ -1147,6 +1233,22 @@ interface VisConfig {
     lockfile?: boolean;
   };
   /**
+  * Behavior of `vis run` when invoked tasks declare service dependencies
+  * that aren't running in the workspace registry. CLI `--services=<mode>`
+  * overrides this block.
+  */
+  run?: {
+    /**
+    * One knob controlling auto-start of missing service deps.
+    * - `auto` (default in TTY): pick by task — `dev` → ephemeral,
+    *   others → persistent.
+    * - `ephemeral`: services die with the run (no registry entry).
+    * - `persistent`: services persist across runs in the registry.
+    * - `off` (default in CI / non-TTY): print diagnostics and abort.
+    */
+    services?: "auto" | "ephemeral" | "off" | "persistent";
+  };
+  /**
   * Default options for `vis secrets`. CLI flags always take precedence;
   * this block provides workspace-wide defaults so teams can commit config
   * once and every invocation picks it up.
@@ -1349,8 +1451,8 @@ interface VisConfig {
   /**
   * Share the cache between sibling git worktrees. When the workspace is a
   * linked worktree (created with `git worktree add`), the cache root is
-  * relocated from `&lt;linkedRoot>/.task-runner-cache` to the *main*
-  * worktree's `.task-runner-cache`. Multiple parallel agents working in
+  * relocated from `&lt;linkedRoot>/.vis/cache` to the *main*
+  * worktree's `.vis/cache`. Multiple parallel agents working in
   * sibling worktrees then share a single cache instead of rebuilding the
   * same hash N times.
   *
@@ -2098,6 +2200,16 @@ interface OtelPluginOptions {
 * ```
 */
 declare const otelPlugin: (options: OtelPluginOptions) => VisPlugin;
+/**
+* Type-safe helper for defining a vis plugin. Pure identity — exists
+* only so plugin authors get inference from the `VisPlugin` contract
+* without needing a `satisfies` annotation.
+*
+* Lives in its own module so plugins can import it without going
+* through `config.ts`, which re-exports plugins like `otelPlugin` and
+* would otherwise form an import cycle.
+*/
+declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
 /** Supported config file names, checked in priority order. */
 declare const CONFIG_FILES: string[];
 /** Per-package overlay file names, checked in priority order. */
@@ -2222,10 +2334,4 @@ declare const defineTaskConfig: (config: VisTaskConfig) => VisTaskConfig;
 * ```
 */
 declare const defineConfig: (config: VisConfig) => VisConfig;
-/**
-* Type-safe helper for defining a vis plugin. Pure identity — exists
-* only so plugin authors get inference from the `VisPlugin` contract
-* without needing a `satisfies` annotation.
-*/
-declare const definePlugin: (plugin: VisPlugin) => VisPlugin;
 export { CONFIG_FILES, type OtelPluginOptions, SECURITY_DEFAULTS, TASK_CONFIG_FILES, type VisConfig, type VisHooks, type VisPlugin, type VisTaskConfig, applyDefaults, defineConfig, definePlugin, defineTaskConfig, findVisConfigFile, findVisTaskConfigFile, loadVisConfig, loadVisTaskConfig, otelPlugin };

package/dist/config/index.js

@@ -1 +1 @@
-import{CONFIG_FILES as o,SECURITY_DEFAULTS as n,TASK_CONFIG_FILES as e,applyDefaults as l,defineConfig as s,definePlugin as C,defineTaskConfig as a,findVisConfigFile as g,findVisTaskConfigFile as d,loadVisConfig as F,loadVisTaskConfig as T}from"../packem_chunks/applyDefaults.js";import{o as S}from"../packem_shared/otel-CO8UEfTa.js";export{o as CONFIG_FILES,n as SECURITY_DEFAULTS,e as TASK_CONFIG_FILES,l as applyDefaults,s as defineConfig,C as definePlugin,a as defineTaskConfig,g as findVisConfigFile,d as findVisTaskConfigFile,F as loadVisConfig,T as loadVisTaskConfig,S as otelPlugin};
+import{p as a,O as f,k as o,l as e,r as n,i as l,j as C,I as g,X as d,e as r}from"../packem_chunks/config.js";import{definePlugin as p}from"../packem_shared/definePlugin-CWm4Dv_t.js";import{otelPlugin as T}from"../packem_shared/otelPlugin-CJR2T_lk.js";export{a as CONFIG_FILES,f as SECURITY_DEFAULTS,o as TASK_CONFIG_FILES,e as applyDefaults,n as defineConfig,p as definePlugin,l as defineTaskConfig,C as findVisConfigFile,g as findVisTaskConfigFile,d as loadVisConfig,r as loadVisTaskConfig,T as otelPlugin};