@holdpoint/types 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/index.d.ts

@@ -1,5 +1,31 @@
-/** Lifecycle hook that fires the check. Currently only "before_done". */
-type HookEvent = "before_done";
+/**
+ * Lifecycle hook a check/action attaches to. `before_done` is the completion
+ * gate (default). The others let checks seed context or run earlier in the loop:
+ * - `session_start`  — a fresh session or resume
+ * - `message_submit` — every user prompt
+ * - `before_tool`    — immediately before a tool call (can block it)
+ * - `after_tool`     — immediately after a tool call (advisory)
+ * - `session_end`    — the session is ending (advisory)
+ * - `before_done`    — the completion gate; blocks finishing on failure
+ *
+ * Engine support varies; engines honor what they can and skip the rest.
+ */
+type HookEvent = "session_start" | "message_submit" | "before_tool" | "after_tool" | "session_end" | "before_done";
+/** Ordered list of all hook events, earliest-to-latest in the agent loop. */
+declare const HOOK_EVENTS: HookEvent[];
+/**
+ * Context-seeding behavior: inject text, file contents, and/or the current
+ * datetime as agent context at the check's hook point. An alternative to
+ * `cmd` (command) and `prompt` (agent instruction).
+ */
+interface InjectSpec {
+    /** Literal text injected as agent context. */
+    text?: string;
+    /** Repo-relative files whose contents are injected as context. */
+    files?: string[];
+    /** Inject the current date and time. */
+    datetime?: boolean;
+}
 /** Named file-scope filter. Custom regexes are plain strings not in this union. */
 type WhenScope = "frontend" | "backend" | "socket" | "visual" | "python" | "go" | "rust" | "java" | "ruby" | "database" | "prisma" | "testing" | "infra" | "ci" | "docs" | "structural";
 type ConditionOperator = "file_exists" | "file_contains" | "env_var_set" | "shell_returns_0";
@@ -26,9 +52,16 @@ interface CheckDef {
     cmd?: string;
     /** Structured prompt/instruction the agent must read and act on before finishing */
     prompt?: string;
+    /** Context-seeding behavior — inject text/files/datetime at the hook point */
+    inject?: InjectSpec;
     /** Reference to a ConditionDef id */
     conditionId?: string;
 }
+/** The effective hook of a check (`before_done` when unset). */
+declare function checkHook(check: CheckDef): HookEvent;
+/** A check's behavior kind, derived from which behavior field is set. */
+type CheckBehavior = "cmd" | "prompt" | "inject";
+declare function checkBehavior(check: CheckDef): CheckBehavior;
 interface HoldpointContext {
     guides: Record<string, string>;
 }
@@ -50,6 +83,27 @@ interface HoldpointConfig {
      * Paths are repo-root-relative. Useful for injecting MASTER_PROMPT.md, AGENT_CONTEXT.md, etc.
      */
     session_context_files?: string[];
+    /**
+     * Inject the current date and time into every prompt submission as `additionalContext`.
+     * Helps models avoid knowledge-cutoff confusion. Defaults to `true`; set to `false` to opt out.
+     */
+    inject_datetime?: boolean;
+    /**
+     * Per-engine overrides. Values here win over engine defaults — useful when the
+     * project IS the holdpoint repo and should invoke the local CLI instead of npx.
+     */
+    engines?: {
+        claude?: {
+            stop_command?: string;
+            live_command?: string;
+        };
+        codex?: {
+            stop_command?: string;
+        };
+        copilot?: {
+            check_command?: string;
+        };
+    };
 }
 type CheckStatus = "pass" | "fail" | "skip" | "pending";
 interface CheckResult {
@@ -70,21 +124,41 @@ interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
 }
-type AgentType = "copilot" | "claude" | "cursor" | "unknown";
-type StackType = "typescript" | "python" | "go" | "nextjs" | "fullstack" | "unknown";
-type NodeKind = "trigger" | "filter" | "task" | "prompt" | "condition";
-interface CanvasNodeData {
-    [key: string]: unknown;
-    kind: NodeKind;
+type AgentType = "copilot" | "claude" | "cursor" | "codex" | "unknown";
+/** Result of a single check within a run (cmd or prompt). */
+interface CheckRunResult {
+    id: string;
     label: string;
-    /** Lifecycle hook on the trigger node */
-    on?: HookEvent;
-    /** File filter on the trigger node */
-    when?: string;
-    cmd?: string;
-    prompt?: string;
-    condition?: ConditionDef;
-    conditionId?: string;
+    /** "cmd" for automated checks, "prompt" for manual agent checks */
+    kind: "cmd" | "prompt";
+    /** "pass" | "fail" | "skip" for cmd checks; "shown" for prompt checks displayed to agent */
+    status: "pass" | "fail" | "skip" | "shown";
+    output?: string;
+    exitCode?: number;
+    skipReason?: string;
+}
+/** A single holdpoint check run recorded after `holdpoint check` completes. */
+interface CheckRun {
+    /** Full HEAD commit SHA, or null if not in a git repo / no commits. */
+    sha: string | null;
+    /** First 8 chars of sha, or null. */
+    shortSha: string | null;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Changed files used for trigger matching. Empty array means "all checks ran". */
+    files: string[];
+    results: CheckRunResult[];
+    summary: {
+        passed: number;
+        failed: number;
+        skipped: number;
+        shown: number;
+    };
+}
+/** Contents of `.holdpoint/check-reports.json` — list of recent check runs. */
+interface CheckReports {
+    /** Runs ordered newest-first. Capped at 50 entries. */
+    runs: CheckRun[];
 }
 
-export type { AgentType, CanvasNodeData, CheckDef, CheckResult, CheckStatus, ConditionDef, ConditionOperator, HoldpointConfig, HoldpointContext, HookEvent, NodeKind, StackType, ValidationError, ValidationResult, WhenScope };
+export { type AgentType, type CheckBehavior, type CheckDef, type CheckReports, type CheckResult, type CheckRun, type CheckRunResult, type CheckStatus, type ConditionDef, type ConditionOperator, HOOK_EVENTS, type HoldpointConfig, type HoldpointContext, type HookEvent, type InjectSpec, type ValidationError, type ValidationResult, type WhenScope, checkBehavior, checkHook };

package/dist/index.js

@@ -1 +1,23 @@
+// src/index.ts
+var HOOK_EVENTS = [
+  "session_start",
+  "message_submit",
+  "before_tool",
+  "after_tool",
+  "session_end",
+  "before_done"
+];
+function checkHook(check) {
+  return check.on ?? "before_done";
+}
+function checkBehavior(check) {
+  if (check.cmd !== void 0) return "cmd";
+  if (check.inject !== void 0) return "inject";
+  return "prompt";
+}
+export {
+  HOOK_EVENTS,
+  checkBehavior,
+  checkHook
+};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// ─── Hook & when types ───────────────────────────────────────────────────────\n\n/**\n * Lifecycle hook a check/action attaches to. `before_done` is the completion\n * gate (default). The others let checks seed context or run earlier in the loop:\n * - `session_start`  — a fresh session or resume\n * - `message_submit` — every user prompt\n * - `before_tool`    — immediately before a tool call (can block it)\n * - `after_tool`     — immediately after a tool call (advisory)\n * - `session_end`    — the session is ending (advisory)\n * - `before_done`    — the completion gate; blocks finishing on failure\n *\n * Engine support varies; engines honor what they can and skip the rest.\n */\nexport type HookEvent =\n  | \"session_start\"\n  | \"message_submit\"\n  | \"before_tool\"\n  | \"after_tool\"\n  | \"session_end\"\n  | \"before_done\";\n\n/** Ordered list of all hook events, earliest-to-latest in the agent loop. */\nexport const HOOK_EVENTS: HookEvent[] = [\n  \"session_start\",\n  \"message_submit\",\n  \"before_tool\",\n  \"after_tool\",\n  \"session_end\",\n  \"before_done\",\n];\n\n/**\n * Context-seeding behavior: inject text, file contents, and/or the current\n * datetime as agent context at the check's hook point. An alternative to\n * `cmd` (command) and `prompt` (agent instruction).\n */\nexport interface InjectSpec {\n  /** Literal text injected as agent context. */\n  text?: string;\n  /** Repo-relative files whose contents are injected as context. */\n  files?: string[];\n  /** Inject the current date and time. */\n  datetime?: boolean;\n}\n\n/** Named file-scope filter. Custom regexes are plain strings not in this union. */\nexport type WhenScope =\n  // Web / app layers\n  | \"frontend\"\n  | \"backend\"\n  | \"socket\"\n  | \"visual\"\n  // Languages\n  | \"python\"\n  | \"go\"\n  | \"rust\"\n  | \"java\"\n  | \"ruby\"\n  // Cross-cutting concerns\n  | \"database\"\n  | \"prisma\"\n  | \"testing\"\n  | \"infra\"\n  | \"ci\"\n  | \"docs\"\n  // Project structure / dependency manifests\n  | \"structural\";\n\n// ─── Condition types ─────────────────────────────────────────────────────────\n\nexport type ConditionOperator = \"file_exists\" | \"file_contains\" | \"env_var_set\" | \"shell_returns_0\";\n\nexport interface ConditionDef {\n  id: string;\n  operator: ConditionOperator;\n  /** Path glob for file_exists / file_contains */\n  path?: string;\n  /** Substring to look for in file_contains */\n  contains?: string;\n  /** Env var name for env_var_set */\n  envVar?: string;\n  /** Shell command for shell_returns_0 */\n  cmd?: string;\n}\n\n// ─── Check types ─────────────────────────────────────────────────────────────\n\nexport interface CheckDef {\n  id: string;\n  label: string;\n  /** Lifecycle hook — defaults to \"before_done\" when absent */\n  on?: HookEvent;\n  /** File filter: a named WhenScope or a regex string. Absent = run always. */\n  when?: string;\n  /** Shell command — task (runs automatically) */\n  cmd?: string;\n  /** Structured prompt/instruction the agent must read and act on before finishing */\n  prompt?: string;\n  /** Context-seeding behavior — inject text/files/datetime at the hook point */\n  inject?: InjectSpec;\n  /** Reference to a ConditionDef id */\n  conditionId?: string;\n}\n\n/** The effective hook of a check (`before_done` when unset). */\nexport function checkHook(check: CheckDef): HookEvent {\n  return check.on ?? \"before_done\";\n}\n\n/** A check's behavior kind, derived from which behavior field is set. */\nexport type CheckBehavior = \"cmd\" | \"prompt\" | \"inject\";\n\nexport function checkBehavior(check: CheckDef): CheckBehavior {\n  if (check.cmd !== undefined) return \"cmd\";\n  if (check.inject !== undefined) return \"inject\";\n  return \"prompt\";\n}\n\n// ─── Top-level config ─────────────────────────────────────────────────────────\n\nexport interface HoldpointContext {\n  guides: Record<string, string>;\n}\n\nexport interface HoldpointConfig {\n  version: number;\n  context: HoldpointContext;\n  conditions: ConditionDef[];\n  /** All checks — each has `on`, optional `when`, and either `cmd` (task) or `prompt` (agent instruction). */\n  checks: CheckDef[];\n  /**\n   * Named regex patterns for use in `when:` fields.\n   * Keys are human-readable names (e.g. \"checks-file\", \"api-routes\").\n   * Values are regex strings matched against changed file paths.\n   * Built-in scope names (frontend, backend, structural, etc.) cannot be overridden here.\n   */\n  patterns?: Record<string, string>;\n  /**\n   * Files to inject as `additionalContext` at the start of every agent session.\n   * Paths are repo-root-relative. Useful for injecting MASTER_PROMPT.md, AGENT_CONTEXT.md, etc.\n   */\n  session_context_files?: string[];\n  /**\n   * Inject the current date and time into every prompt submission as `additionalContext`.\n   * Helps models avoid knowledge-cutoff confusion. Defaults to `true`; set to `false` to opt out.\n   */\n  inject_datetime?: boolean;\n  /**\n   * Per-engine overrides. Values here win over engine defaults — useful when the\n   * project IS the holdpoint repo and should invoke the local CLI instead of npx.\n   */\n  engines?: {\n    claude?: { stop_command?: string; live_command?: string };\n    codex?: { stop_command?: string };\n    copilot?: { check_command?: string };\n  };\n}\n\n// ─── Runtime result types ────────────────────────────────────────────────────\n\nexport type CheckStatus = \"pass\" | \"fail\" | \"skip\" | \"pending\";\n\nexport interface CheckResult {\n  check: CheckDef;\n  status: CheckStatus;\n  /** stdout/stderr from a deterministic check */\n  output?: string;\n  /** Exit code from a deterministic check */\n  exitCode?: number;\n  /** Human-readable reason for skip */\n  skipReason?: string;\n}\n\nexport interface ValidationError {\n  path: string;\n  message: string;\n}\n\nexport interface ValidationResult {\n  valid: boolean;\n  errors: ValidationError[];\n}\n\n// ─── Agent detection ─────────────────────────────────────────────────────────\n\nexport type AgentType = \"copilot\" | \"claude\" | \"cursor\" | \"codex\" | \"unknown\";\n\n// ─── Check run report types ────────────────────────────────────────────────────\n\n/** Result of a single check within a run (cmd or prompt). */\nexport interface CheckRunResult {\n  id: string;\n  label: string;\n  /** \"cmd\" for automated checks, \"prompt\" for manual agent checks */\n  kind: \"cmd\" | \"prompt\";\n  /** \"pass\" | \"fail\" | \"skip\" for cmd checks; \"shown\" for prompt checks displayed to agent */\n  status: \"pass\" | \"fail\" | \"skip\" | \"shown\";\n  output?: string;\n  exitCode?: number;\n  skipReason?: string;\n}\n\n/** A single holdpoint check run recorded after `holdpoint check` completes. */\nexport interface CheckRun {\n  /** Full HEAD commit SHA, or null if not in a git repo / no commits. */\n  sha: string | null;\n  /** First 8 chars of sha, or null. */\n  shortSha: string | null;\n  /** ISO 8601 timestamp. */\n  timestamp: string;\n  /** Changed files used for trigger matching. Empty array means \"all checks ran\". */\n  files: string[];\n  results: CheckRunResult[];\n  summary: { passed: number; failed: number; skipped: number; shown: number };\n}\n\n/** Contents of `.holdpoint/check-reports.json` — list of recent check runs. */\nexport interface CheckReports {\n  /** Runs ordered newest-first. Capped at 50 entries. */\n  runs: CheckRun[];\n}\n"],"mappings":";AAuBO,IAAM,cAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA4EO,SAAS,UAAU,OAA4B;AACpD,SAAO,MAAM,MAAM;AACrB;AAKO,SAAS,cAAc,OAAgC;AAC5D,MAAI,MAAM,QAAQ,OAAW,QAAO;AACpC,MAAI,MAAM,WAAW,OAAW,QAAO;AACvC,SAAO;AACT;","names":[]}

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@holdpoint/types",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "description": "Shared TypeScript types for Holdpoint",
   "homepage": "https://holdpoint.dev",
@@ -44,7 +43,7 @@
   ],
   "devDependencies": {
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "build": "tsup",