@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/__tests__/command-plugins-surfaces.test.js

@@ -0,0 +1,298 @@
+// Phase-2 surface tests: the lifecycle surfaces (pkg plugin install / show and
+// sys doctor) must surface the Phase-1 validator's STABLE TYPED ISSUES to the
+// caller, and must do so WITHOUT executing the plugin binary. Covers spec item
+// 6 at the surface seam (the validator itself is tested in
+// command-plugins.test.ts). Run with:
+//   node --import tsx/esm --test src/core/__tests__/command-plugins-surfaces.test.ts
+//
+// Every test runs against an ISOLATED home (HOME → temp) with cwd pinned to a
+// dir that has no .crouter ancestor, so discovery is deterministic. Each fixture
+// executable writes a sentinel file if it is ever spawned; every surface
+// assertion also checks the sentinel is absent — proving validation stayed
+// static.
+import { test, describe, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, chmodSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pluginInstall, pluginUpdate } from '../../commands/pkg/plugin-manage.js';
+import { pluginShow } from '../../commands/pkg/plugin-inspect.js';
+import { sysDoctorLeaf } from '../../commands/sys/doctor.js';
+import { discoverCommandContributions } from '../command-plugins/discovery.js';
+import { resetScopeCache } from '../scope.js';
+// A real executable that records the fact it ran. No surface should ever spawn
+// it — the sentinel must never appear.
+const SENTINEL_EXEC = `#!/usr/bin/env node
+const fs = require('fs');
+if (process.env.CMDPLUGIN_SENTINEL) fs.writeFileSync(process.env.CMDPLUGIN_SENTINEL, 'executed');
+process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { app_id: 'x', status: 'running' } }));
+`;
+function validManifest() {
+    return {
+        schemaVersion: 1,
+        executable: 'bin/cmd.js',
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'app',
+                    description: 'application lifecycle and inspection',
+                    whenToUse: 'you need to create, deploy, inspect, or remove an application',
+                    rootEntry: {
+                        concept: 'applications hosted by a crouter home',
+                        description: 'application lifecycle and inspection',
+                        whenToUse: 'you need to create, deploy, inspect, or remove an application',
+                    },
+                    summary: 'application lifecycle and inspection',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: 'show one application',
+                            whenToUse: 'inspect a single application by id',
+                            summary: 'show one application details',
+                            params: [{ kind: 'positional', name: 'app-id', required: true, constraint: 'the application id' }],
+                            output: [{ name: 'app_id', type: 'string', required: true, constraint: 'the echoed application id' }],
+                            outputKind: 'object',
+                            effects: ['None. Read-only.'],
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+}
+const CASES = [
+    (() => { const m = validManifest(); m['executable'] = '../../../../bin/sh'; return { name: 'escaping executable path', code: 'command_path_unsafe', manifest: m }; })(),
+    { name: 'non-executable file', code: 'command_not_executable', execBit: false },
+    (() => { const m = validManifest(); m['schemaVersion'] = 2; return { name: 'unknown schemaVersion', code: 'command_schema_version', manifest: m }; })(),
+    (() => { const m = validManifest(); m['requires'] = { crtr: '>=1' }; return { name: 'unknown top-level key', code: 'command_manifest_invalid', manifest: m }; })(),
+    (() => { const m = validManifest(); m['mounts'][0].parent = ['sys']; return { name: 'non-empty parent', code: 'command_parent_invalid', manifest: m }; })(),
+];
+// ---------------------------------------------------------------------------
+// Isolated home + cwd
+// ---------------------------------------------------------------------------
+let home;
+let userRoot;
+let emptyStart;
+let sourceRoot; // holds source plugin dirs for install tests
+let sentinel;
+let realHome;
+let realProfile;
+let realCwd;
+before(() => {
+    realHome = process.env['HOME'];
+    realProfile = process.env['CRTR_PROFILE_ID'];
+    realCwd = process.cwd();
+    delete process.env['CRTR_PROFILE_ID'];
+});
+after(() => {
+    process.chdir(realCwd);
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+    if (realProfile !== undefined)
+        process.env['CRTR_PROFILE_ID'] = realProfile;
+    delete process.env['CMDPLUGIN_SENTINEL'];
+    // Remove EVERY test's temp dirs, not just the last beforeEach's set.
+    for (const d of tempDirs) {
+        try {
+            rmSync(d, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    resetScopeCache();
+});
+const tempDirs = [];
+function mintDir(prefix) {
+    const d = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(d);
+    return d;
+}
+beforeEach(() => {
+    home = mintDir('crtr-cmdsurf-home-');
+    process.env['HOME'] = home;
+    userRoot = join(home, '.crouter');
+    mkdirSync(join(userRoot, 'plugins'), { recursive: true });
+    emptyStart = mintDir('crtr-cmdsurf-empty-');
+    sourceRoot = mintDir('crtr-cmdsurf-src-');
+    sentinel = join(emptyStart, 'EXECUTED');
+    process.env['CMDPLUGIN_SENTINEL'] = sentinel;
+    process.chdir(emptyStart); // no .crouter ancestor → project scope is empty
+    resetScopeCache();
+});
+/** Write a plugin at `<dir>/<name>/` with a command manifest + executable. */
+function writePlugin(dir, name, c) {
+    const root = join(dir, name);
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name, version: '0.1.0', description: 'fixture', commands: 'commands.json' }));
+    writeFileSync(join(root, 'commands.json'), JSON.stringify(c.manifest ?? validManifest()));
+    const execPath = join(root, 'bin', 'cmd.js');
+    writeFileSync(execPath, SENTINEL_EXEC);
+    chmodSync(execPath, c.execBit === false ? 0o644 : 0o755);
+    return root;
+}
+function assertNotExecuted() {
+    assert.equal(existsSync(sentinel), false, 'the plugin binary must never be spawned by a validation surface');
+}
+// ---------------------------------------------------------------------------
+// pkg plugin show
+// ---------------------------------------------------------------------------
+describe('pkg plugin show surfaces command validation', () => {
+    for (const c of CASES) {
+        test(`${c.name} → ${c.code} in commands.issues, no execution`, async () => {
+            writePlugin(join(userRoot, 'plugins'), 'p', c);
+            resetScopeCache();
+            const out = await pluginShow.run({ name: 'p' });
+            const commands = out['commands'];
+            assert.ok(commands, 'show must inventory commands for a plugin declaring a manifest');
+            assert.ok(commands.issues.some((i) => i.code === c.code), `expected ${c.code}, got ${JSON.stringify(commands.issues.map((i) => i.code))}`);
+            // Typed issues render with received/expected/next.
+            const issue = commands.issues.find((i) => i.code === c.code);
+            assert.ok(typeof issue.received === 'string' && typeof issue.expected === 'string' && typeof issue.next === 'string');
+            assert.equal(commands.mounts.length, 0, 'a rejected manifest contributes no mounts');
+            assertNotExecuted();
+        });
+    }
+    test('valid manifest → inventory with the accepted mount and zero issues', async () => {
+        writePlugin(join(userRoot, 'plugins'), 'p', { name: 'valid', code: '' });
+        resetScopeCache();
+        const out = await pluginShow.run({ name: 'p' });
+        const commands = out['commands'];
+        assert.deepEqual(commands.mounts, ['app']);
+        assert.equal(commands.issues.length, 0);
+        assert.ok(typeof commands.executable === 'string', 'executable path is resolved for a valid manifest');
+        assertNotExecuted();
+    });
+});
+// ---------------------------------------------------------------------------
+// sys doctor
+// ---------------------------------------------------------------------------
+describe('sys doctor surfaces command validation', () => {
+    for (const c of CASES) {
+        test(`${c.name} → fail check with human_action remediation, no execution`, async () => {
+            writePlugin(join(userRoot, 'plugins'), 'p', c);
+            resetScopeCache();
+            const out = await sysDoctorLeaf.run({ scope: 'user', fix: false, remote: false });
+            const checks = out['checks'];
+            const cmdCheck = checks.find((k) => k.name.startsWith('plugin:p:commands') && k.status === 'fail');
+            assert.ok(cmdCheck, `expected a failing command check, got ${JSON.stringify(checks.map((k) => k.name + ':' + k.status))}`);
+            assert.match(cmdCheck.message, new RegExp(c.code));
+            assert.equal(cmdCheck.remediation?.kind, 'human_action', 'command remediation is never auto-applied');
+            assert.equal(out['ok'], false);
+            assertNotExecuted();
+        });
+    }
+    test('--fix never touches plugin content and leaves the command issue unresolved', async () => {
+        writePlugin(join(userRoot, 'plugins'), 'p', { name: 'non-executable file', code: 'command_not_executable', execBit: false });
+        resetScopeCache();
+        const out = await sysDoctorLeaf.run({ scope: 'user', fix: true, remote: false });
+        const checks = out['checks'];
+        const cmdCheck = checks.find((k) => k.name.startsWith('plugin:p:commands') && k.status === 'fail');
+        assert.ok(cmdCheck, 'the command issue is still reported under --fix');
+        assert.notEqual(cmdCheck.fixed, true, '--fix must not chmod the plugin executable');
+        assertNotExecuted();
+    });
+    test('valid manifest → a passing command check', async () => {
+        writePlugin(join(userRoot, 'plugins'), 'p', { name: 'valid', code: '' });
+        resetScopeCache();
+        const out = await sysDoctorLeaf.run({ scope: 'user', fix: false, remote: false });
+        const checks = out['checks'];
+        const cmdCheck = checks.find((k) => k.name === 'plugin:p:commands');
+        assert.ok(cmdCheck && cmdCheck.status === 'pass', 'a valid manifest yields a pass check');
+        assert.match(cmdCheck.message, /app/);
+        assertNotExecuted();
+    });
+});
+// ---------------------------------------------------------------------------
+// Cross-plugin top-level collision (drop-both + issue, visible on surfaces)
+// ---------------------------------------------------------------------------
+describe('cross-plugin top-level collision surfaces on doctor and show', () => {
+    function installTwoClaimants() {
+        // Two distinct plugins, both valid in isolation, both claiming `app`.
+        writePlugin(join(userRoot, 'plugins'), 'p-one', { name: 'valid', code: '' });
+        writePlugin(join(userRoot, 'plugins'), 'p-two', { name: 'valid', code: '' });
+        resetScopeCache();
+    }
+    test('neither claimant mounts: discovery drops the collided command from the tree', () => {
+        installTwoClaimants();
+        const snapshot = discoverCommandContributions(new Set(['sys']));
+        assert.equal(snapshot.contributions.length, 0, 'a collided top-level command must not be mounted by ANY claimant');
+        const collisions = snapshot.issues.filter((i) => i.code === 'command_collision');
+        assert.deepEqual(collisions.map((i) => i.plugin).sort(), ['p-one', 'p-two'], 'both claimants are flagged');
+    });
+    test('sys doctor fails BOTH claimants with the collision (no false pass)', async () => {
+        installTwoClaimants();
+        const out = await sysDoctorLeaf.run({ scope: 'user', fix: false, remote: false });
+        const checks = out['checks'];
+        for (const name of ['p-one', 'p-two']) {
+            const passCheck = checks.find((k) => k.name === `plugin:${name}:commands` && k.status === 'pass');
+            assert.equal(passCheck, undefined, `${name} must not PASS while its command is dropped by a collision`);
+            const failCheck = checks.find((k) => k.name.startsWith(`plugin:${name}:commands`) && k.status === 'fail' && /command_collision/.test(k.message));
+            assert.ok(failCheck, `${name} must fail with command_collision, got ${JSON.stringify(checks.map((k) => k.name + ':' + k.status))}`);
+            assert.match(failCheck.message, /claimed by multiple plugins/);
+            assert.match(failCheck.message, /p-one/);
+            assert.match(failCheck.message, /p-two/);
+            assert.equal(failCheck.remediation?.kind, 'human_action');
+        }
+        assert.equal(out['ok'], false);
+        assertNotExecuted();
+    });
+    test('pkg plugin show reports the collision on each claimant and lists no mounts', async () => {
+        installTwoClaimants();
+        for (const name of ['p-one', 'p-two']) {
+            const out = await pluginShow.run({ name });
+            const commands = out['commands'];
+            assert.deepEqual(commands.mounts, [], `${name} must not list the collided command as an accepted mount`);
+            const issue = commands.issues.find((i) => i.code === 'command_collision');
+            assert.ok(issue, `${name} show must carry the command_collision issue`);
+            assert.deepEqual(issue.received.split(', ').sort(), ['p-one', 'p-two'], 'the issue names both claimants');
+        }
+        assertNotExecuted();
+    });
+});
+// ---------------------------------------------------------------------------
+// pkg plugin install / update
+// ---------------------------------------------------------------------------
+describe('pkg plugin install/update surface command validation', () => {
+    for (const c of CASES) {
+        test(`install ${c.name} → ${c.code} in result.commands.issues, no execution`, async () => {
+            const src = writePlugin(sourceRoot, 'p', c);
+            resetScopeCache();
+            const out = await pluginInstall.run({ installRef: src, scope: 'user' });
+            const commands = out['commands'];
+            assert.ok(commands, 'install reports command validation for a plugin declaring a manifest');
+            assert.ok(commands.issues.some((i) => i.code === c.code), `expected ${c.code}, got ${JSON.stringify(commands.issues.map((i) => i.code))}`);
+            assert.equal(commands.mounts.length, 0);
+            assertNotExecuted();
+        });
+    }
+    test('install valid manifest → accepted contribution, zero issues, no execution', async () => {
+        const src = writePlugin(sourceRoot, 'p', { name: 'valid', code: '' });
+        resetScopeCache();
+        const out = await pluginInstall.run({ installRef: src, scope: 'user' });
+        const commands = out['commands'];
+        assert.deepEqual(commands.mounts, ['app']);
+        assert.equal(commands.issues.length, 0);
+        assertNotExecuted();
+    });
+    test('update re-reports the current command validation for an edited manifest', async () => {
+        // Install valid, then break the on-disk manifest, then update: the report
+        // must reflect the CURRENT (broken) state — validation is per-call.
+        const src = writePlugin(sourceRoot, 'p', { name: 'valid', code: '' });
+        resetScopeCache();
+        await pluginInstall.run({ installRef: src, scope: 'user' });
+        // Break the installed copy's manifest in place.
+        writeFileSync(join(userRoot, 'plugins', 'p', 'commands.json'), JSON.stringify((() => { const m = validManifest(); m['schemaVersion'] = 2; return m; })()));
+        resetScopeCache();
+        const out = await pluginUpdate.run({ name: 'p' });
+        const updated = out['updated'];
+        const entry = updated.find((u) => u.name === 'p');
+        assert.ok(entry.commands, 'update reports command validation');
+        assert.ok(entry.commands.issues.some((i) => i.code === 'command_schema_version'));
+        assertNotExecuted();
+    });
+});

package/dist/core/__tests__/command-plugins.test.d.ts

@@ -0,0 +1 @@
+export {};