test: add behavioral alias dispatch contract

tests/feat-3251-command-aliases-manifest-coverage.test.cjs

@@ -10,7 +10,10 @@
 
 const { describe, test } = require('node:test');
 const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
 const path = require('path');
+const { spawnSync } = require('node:child_process');
 
 const REPO_ROOT = path.join(__dirname, '..');
 const COMMAND_ALIASES_FILE = path.join(
@@ -20,6 +23,7 @@ const COMMAND_ALIASES_FILE = path.join(
   'lib',
   'command-aliases.generated.cjs',
 );
+const GSD_TOOLS = path.join(REPO_ROOT, 'get-shit-done', 'bin', 'gsd-tools.cjs');
 
 const MISSING_14 = [
   'check.decision-coverage-plan',
@@ -126,3 +130,105 @@ describe('feat-3251: command-aliases.generated.cjs manifest coverage', () => {
     );
   });
 });
+
+function createProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-3251-dispatch-'));
+  fs.mkdirSync(path.join(dir, '.planning', 'phases'), { recursive: true });
+  return dir;
+}
+
+function runGsdTools(args, cwd) {
+  return spawnSync(process.execPath, [GSD_TOOLS, ...args], {
+    cwd,
+    encoding: 'utf8',
+  });
+}
+
+function listProjectFiles(projectDir) {
+  const files = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(projectDir, full);
+      if (entry.isDirectory()) walk(full);
+      else files.push(rel);
+    }
+  }
+  walk(projectDir);
+  return files.sort();
+}
+
+describe('feat-3251: generated aliases dispatch through real gsd-tools behavior', () => {
+  test('phase.mvp-mode spaced alias resolves CLI flag precedence', () => {
+    const projectDir = createProject();
+    try {
+      const result = runGsdTools(['phase', 'mvp-mode', '1', '--cli-flag'], projectDir);
+      assert.equal(result.status, 0, result.stderr);
+
+      const output = JSON.parse(result.stdout);
+      assert.deepEqual(output, {
+        active: true,
+        source: 'cli_flag',
+        roadmap_mode: null,
+        config_mvp_mode: false,
+        cli_flag_present: true,
+      });
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test('phase.mvp-mode spaced alias resolves ROADMAP mode without mutating files', () => {
+    const projectDir = createProject();
+    try {
+      fs.writeFileSync(
+        path.join(projectDir, '.planning', 'ROADMAP.md'),
+        [
+          '# Roadmap',
+          '',
+          '## v1.0.0',
+          '',
+          '### Phase 1: User Auth',
+          '**Goal:** Users can sign in.',
+          '**Mode:** mvp',
+          '',
+        ].join('\n'),
+      );
+      const beforeFiles = listProjectFiles(projectDir);
+
+      const result = runGsdTools(['phase', 'mvp-mode', '1'], projectDir);
+      assert.equal(result.status, 0, result.stderr);
+
+      const output = JSON.parse(result.stdout);
+      assert.equal(output.active, true);
+      assert.equal(output.source, 'roadmap');
+      assert.equal(output.roadmap_mode, 'mvp');
+      assert.equal(output.config_mvp_mode, false);
+      assert.equal(output.cli_flag_present, false);
+      assert.deepEqual(listProjectFiles(projectDir), beforeFiles);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test('phase.mvp-mode JSON error is typed and leaves project files untouched', () => {
+    const projectDir = createProject();
+    try {
+      const beforeFiles = listProjectFiles(projectDir);
+      const result = runGsdTools(['--json-errors', 'phase', 'mvp-mode'], projectDir);
+      assert.notEqual(result.status, 0);
+      assert.equal(result.stdout, '');
+
+      const error = JSON.parse(result.stderr);
+      assert.deepEqual(Object.keys(error).sort(), ['message', 'ok', 'reason']);
+      assert.equal(error.ok, false);
+      assert.equal(error.reason, 'usage');
+      assert.equal(typeof error.message, 'string');
+      assert.equal(/\n\s*at\s/.test(result.stderr), false, 'non-debug failure must not print a stack trace');
+      assert.deepEqual(listProjectFiles(projectDir), beforeFiles);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});