@agentpulselabs/cli-plugin-pulse 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentPulse Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+[`@agentpulselabs/pulse`](https://github.com/ashishcloud/agentpulse-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.

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@agentpulselabs/cli-plugin-pulse",
-  "version": "0.1.0",
+  "version": "0.2.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"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashishcloud/agentpulse-cli-plugin-pulse.git"
+  },
+  "homepage": "https://github.com/ashishcloud/agentpulse-cli-plugin-pulse#readme",
+  "bugs": {
+    "url": "https://github.com/ashishcloud/agentpulse-cli-plugin-pulse/issues"
+  },
   "files": [
     "src",
     "README.md"

package/src/commands/pulse/gate.js

@@ -1,8 +1,9 @@
-import { Command, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 import { runPulse } from '../../runPulse.js';
 
 /** `agentpulse pulse gate` — the human-in-the-loop barrier. Advance only with --approved. */
-export default class PulseGate extends Command {
+export default class PulseGate extends BaseCommand {
   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 = {
@@ -18,6 +19,7 @@ export default class PulseGate extends Command {
       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));
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    return result;                              // --json: standard envelope
   }
 }

package/src/commands/pulse/next.js

@@ -1,13 +1,14 @@
-import { Command } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 import { runPulse } from '../../runPulse.js';
 
 /** `agentpulse pulse next` — emit the current phase work-list (prompts + schema, contract injected). */
-export default class PulseNext extends Command {
+export default class PulseNext extends BaseCommand {
   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));
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    return result;                              // --json: standard envelope
   }
 }

package/src/commands/pulse/start.js

@@ -1,8 +1,9 @@
-import { Command, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 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 {
+export default class PulseStart extends BaseCommand {
   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 = {
@@ -19,6 +20,7 @@ export default class PulseStart extends Command {
       ? 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));
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    return result;                              // --json: standard envelope
   }
 }

package/src/commands/pulse/status.js

@@ -1,13 +1,14 @@
-import { Command } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 import { runPulse } from '../../runPulse.js';
 
 /** `agentpulse pulse status` — where does the engagement stand? Phase, contract, board progress. */
-export default class PulseStatus extends Command {
+export default class PulseStatus extends BaseCommand {
   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));
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    return result;                              // --json: standard envelope
   }
 }

package/src/commands/pulse/submit.js

@@ -1,8 +1,9 @@
-import { Command, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 import { runPulse } from '../../runPulse.js';
 
 /** `agentpulse pulse submit` — validate the model's structured results against schema + contract. */
-export default class PulseSubmit extends Command {
+export default class PulseSubmit extends BaseCommand {
   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 = {
@@ -14,6 +15,7 @@ export default class PulseSubmit extends Command {
     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));
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    return result;                              // --json: standard envelope
   }
 }

package/src/commands/pulse/verify.js

@@ -1,8 +1,9 @@
-import { Command, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
 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 {
+export default class PulseVerify extends BaseCommand {
   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 = {
@@ -12,7 +13,9 @@ export default class PulseVerify extends Command {
   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
+    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
+    // A red gate is a SUCCESSFUL run reporting ok:false + exit 1 (so CI/scripts gate on it) — not a thrown error.
+    if (!result.green) return this.problem(result, 1);
+    return result;                              // --json: standard envelope
   }
 }

package/src/lib/BaseCommand.js

@@ -0,0 +1,37 @@
+import { Command } from '@oclif/core';
+
+/**
+ * BaseCommand — the pulse plugin's half of the machine-readable CLI contract (docs/PLAN.md M0), matching the host
+ * CLI's BaseCommand so `agentpulse pulse <verb> --json` yields the SAME standard envelope as first-party commands:
+ *
+ *   success:  { tool:'agentpulse', command:'pulse status', version, ok:true,  result }
+ *   error:    { tool:'agentpulse', command:'pulse status', version, ok:false, error:{ code, message } }
+ *
+ * Behavior note (deliberate, back-compat): pulse output is machine-oriented (work-lists with prompts + JSON
+ * schemas an agent consumes), so the DEFAULT (no --json) still prints the raw engine result as pretty JSON —
+ * exactly as before. `--json` layers the standard envelope on top. Both are JSON; --json is the stable contract.
+ */
+export default class BaseCommand extends Command {
+  static enableJsonFlag = true;
+
+  toSuccessJson(result) {
+    const marked = result && typeof result === 'object' && result.__ap === true;
+    const ok = marked ? result.ok : true;
+    const payload = marked ? result.result : result;
+    return { tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok, result: payload };
+  }
+
+  toErrorJson(err) {
+    return {
+      tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok: false,
+      error: { code: (err && err.code) || 'E_ERROR', message: (err && err.message) || String(err) },
+    };
+  }
+
+  commandName() { return String(this.id || this.ctor?.id || '').replace(/:/g, ' '); }
+
+  fail(code, message, exit = 1) { process.exitCode = exit; this.error(message, { code, exit }); }
+
+  /** A successful run that reports ok:false and exits non-zero, carrying its full payload (e.g. `verify` red). */
+  problem(payload, exit = 1) { process.exitCode = exit; return { __ap: true, ok: false, result: payload }; }
+}