@agentpulselabs/cli-plugin-pulse 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @agentpulselabs/cli-plugin-pulse
+
+An [oclif](https://oclif.io) plugin that adds the **`pulse`** topic — a portable, contract-enforced build
+discipline — to the `agentpulse` CLI. It is a thin `argv → core → stdout` seam over
+[`@agentpulselabs/pulse`](../pulse); all discipline lives in the core.
+
+> **Published to public npm** under the `@agentpulselabs` org (`publishConfig.access: "public"`). The CLI
+> (`@agentpulselabs/cli`) supports plugins via `@oclif/plugin-plugins`; this plugin installs through it.
+
+## Install
+
+```bash
+npm i -g @agentpulselabs/cli                              # the CLI (if not already installed)
+agentpulse plugins install @agentpulselabs/cli-plugin-pulse
+agentpulse pulse --help
+```
+
+This is the **user-installed** integration path (design decision): opt-in, decoupled release cadence, and the
+same mechanism any third party uses to add `agentpulse` commands.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agentpulse pulse start --requirements "…" --name <name>` | Begin an engagement in the current repo (`.pulse/`). |
+| `agentpulse pulse next` | Emit the current phase work-list (prompts + JSON schema; contract injected). |
+| `agentpulse pulse submit --results-file r.json` | Validate your model's structured results vs schema + contract. |
+| `agentpulse pulse gate --approved [--decisions-file d.json]` | The human gate — advance the phase; lock product decisions. |
+| `agentpulse pulse verify` | Run the contract's gate command (`npm run check`); exits non-zero if red. |
+| `agentpulse pulse status` | Phase, contract, board progress. |
+
+The MCP server (`pulse-mcp`, shipped by `@agentpulselabs/pulse`) is the primary seam for interactive agents
+(Cursor/Codex/Claude). This CLI plugin is the universal shell fallback: same core, same `.pulse/` state.
+
+## Architecture
+
+```
+argv → src/commands/pulse/<verb>.js  (thin oclif Command, parses flags)
+          → src/runPulse.js           (pure: verb → engine method; no oclif, testable)
+             → @agentpulselabs/pulse       (the brain: state machine + contract + validator + gates)
+                → .pulse/ in the repo  (durable, git-tracked truth)
+```
+
+## Test
+
+```bash
+node --test "test/**/*.test.js"   # exercises runPulse over a real .pulse/, no @oclif/core needed
+```

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentpulselabs/cli-plugin-pulse",
+  "version": "0.1.0",
+  "description": "oclif plugin that adds the `pulse` topic (portable, contract-enforced build discipline) to the agentpulse CLI. User-installed: `agentpulse plugins install @agentpulselabs/cli-plugin-pulse`. A thin argv→core seam over @agentpulselabs/pulse.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "oclif": {
+    "commands": "./src/commands",
+    "topicSeparator": " ",
+    "topics": {
+      "pulse": {
+        "description": "Run a contract-enforced build discipline engagement (Discovery → Stories → Architecture → Build → Deliver)."
+      }
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "oclif-plugin",
+    "agentpulse",
+    "pulse",
+    "cli"
+  ],
+  "dependencies": {
+    "@agentpulselabs/pulse": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@oclif/core": ">=3"
+  }
+}

package/src/commands/pulse/gate.js

@@ -0,0 +1,23 @@
+import { Command, Flags } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse gate` — the human-in-the-loop barrier. Advance only with --approved. */
+export default class PulseGate extends Command {
+  static description = 'The human gate. Advance the phase ONLY with --approved. Lock product decisions here.';
+  static examples = ['<%= config.bin %> pulse gate --approved --decisions-file decisions.json'];
+  static flags = {
+    approved: Flags.boolean({ description: 'Approve this phase (silence/omission = not approved).', default: false }),
+    'decisions-file': Flags.string({ description: 'Path to a JSON file of human product decisions to lock: [{ title, decision, rationale }].' }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseGate);
+    let decisions = [];
+    if (flags['decisions-file']) {
+      const fs = await import('node:fs');
+      decisions = JSON.parse(fs.readFileSync(flags['decisions-file'], 'utf8'));
+    }
+    const result = await runPulse('gate', { approved: flags.approved, decisions });
+    this.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/pulse/next.js

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse next` — emit the current phase work-list (prompts + schema, contract injected). */
+export default class PulseNext extends Command {
+  static description = 'Emit the current phase work-list: tasks (prompt + JSON schema) your model must run.';
+  static examples = ['<%= config.bin %> pulse next'];
+
+  async run() {
+    const result = await runPulse('next', {});
+    this.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/pulse/start.js

@@ -0,0 +1,24 @@
+import { Command, Flags } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse start` — begin an engagement in the current repo (.pulse/). Thin argv→core shim. */
+export default class PulseStart extends Command {
+  static description = 'Begin a Pulse engagement in the current repo (.pulse/).';
+  static examples = ['<%= config.bin %> pulse start --requirements "Build a widget store" --name widgets'];
+  static flags = {
+    requirements: Flags.string({ description: 'Raw requirements text (or use --requirements-file).', required: false }),
+    'requirements-file': Flags.string({ description: 'Path to a file containing the requirements.' }),
+    grounding: Flags.string({ description: 'Optional domain grounding notes.' }),
+    name: Flags.string({ description: 'Short engagement name (used for filenames).', default: 'engagement' }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseStart);
+    const fs = await import('node:fs');
+    const requirements = flags['requirements-file']
+      ? fs.readFileSync(flags['requirements-file'], 'utf8')
+      : (flags.requirements || '');
+    const result = await runPulse('start', { requirements, grounding: flags.grounding, name: flags.name });
+    this.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/pulse/status.js

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse status` — where does the engagement stand? Phase, contract, board progress. */
+export default class PulseStatus extends Command {
+  static description = 'Show engagement status: phase, contract, board progress.';
+  static examples = ['<%= config.bin %> pulse status'];
+
+  async run() {
+    const result = await runPulse('status', {});
+    this.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/pulse/submit.js

@@ -0,0 +1,19 @@
+import { Command, Flags } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse submit` — validate the model's structured results against schema + contract. */
+export default class PulseSubmit extends Command {
+  static description = "Submit your model's structured results (JSON). Pulse validates them vs schema + contract.";
+  static examples = ['<%= config.bin %> pulse submit --results-file discovery-results.json'];
+  static flags = {
+    'results-file': Flags.string({ description: 'Path to a JSON file: [{ id, data }, …] (one per work-list task).', required: true }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseSubmit);
+    const fs = await import('node:fs');
+    const results = JSON.parse(fs.readFileSync(flags['results-file'], 'utf8'));
+    const result = await runPulse('submit', { results });
+    this.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/pulse/verify.js

@@ -0,0 +1,18 @@
+import { Command, Flags } from '@oclif/core';
+import { runPulse } from '../../runPulse.js';
+
+/** `agentpulse pulse verify` — run the contract's deterministic gate command. "Done" is this exit code. */
+export default class PulseVerify extends Command {
+  static description = "Run the contract's gate command (e.g. `npm run check`) and report pass/fail. Never an LLM opinion.";
+  static examples = ['<%= config.bin %> pulse verify'];
+  static flags = {
+    cwd: Flags.string({ description: 'Directory to run the gate in (default: current repo).' }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseVerify);
+    const result = await runPulse('verify', { cwd: flags.cwd });
+    this.log(JSON.stringify(result, null, 2));
+    if (!result.green) this.exit(1); // non-zero so CI / scripts can gate on it
+  }
+}

package/src/runPulse.js

@@ -0,0 +1,58 @@
+/**
+ * runPulse.js — the PURE command core for the pulse CLI topic. Maps a verb + args → an engine call → a
+ * JSON-serializable result. No oclif, no I/O of its own (the engine's state.js owns fs). This is what makes
+ * the plugin testable without installing @oclif/core, and keeps the seam thin: the oclif command classes
+ * (src/commands/pulse/*.js) are ~5-line wrappers that parse flags and call this.
+ *
+ * Mirror of the MCP seam's tools.js: one verb == one engine method. All discipline lives in @agentpulselabs/pulse.
+ */
+
+import { createEngine } from '@agentpulselabs/pulse';
+
+/** The verbs this topic exposes, each → an engine method. Kept in sync with the MCP tool surface. */
+export const ACTIONS = ['start', 'next', 'submit', 'gate', 'verify', 'status', 'board', 'claim', 'sync'];
+
+/**
+ * @param {string} action - one of ACTIONS
+ * @param {Object} args   - parsed flags/inputs for the action
+ * @param {Object} [opts] - { cwd, createEngine } (createEngine injectable for tests)
+ * @returns {Promise<Object>} JSON-serializable result
+ */
+export async function runPulse(action, args = {}, opts = {}) {
+  const make = opts.createEngine || createEngine;
+  const engine = make({ cwd: opts.cwd || process.cwd() });
+
+  switch (action) {
+    case 'start':
+      return engine.start({ requirements: args.requirements, grounding: args.grounding, name: args.name });
+    case 'next':
+      return engine.next();
+    case 'submit':
+      return engine.submit({ results: parseResults(args.results) });
+    case 'gate':
+      return engine.gate({ approved: !!args.approved, decisions: parseJson(args.decisions, []) });
+    case 'verify':
+      return await engine.verify({ cwd: args.cwd });
+    case 'status':
+      return engine.status();
+    case 'board':
+      return engine.boardUpdate({ id: args.id, status: args.status });
+    case 'claim':
+      return engine.claim({ id: args.id, agentId: args.agentId });
+    case 'sync':
+      return engine.sync({ ids: parseJson(args.ids, undefined) });
+    default:
+      throw new Error(`unknown pulse action "${action}" — expected one of ${ACTIONS.join(', ')}`);
+  }
+}
+
+// results may arrive as a JSON string (from --results-file content) or already-parsed array.
+function parseResults(r) {
+  if (Array.isArray(r)) return r;
+  return parseJson(r, []);
+}
+function parseJson(v, fallback) {
+  if (v == null) return fallback;
+  if (typeof v !== 'string') return v;
+  try { return JSON.parse(v); } catch { return fallback; }
+}