@freshworks/shiftleft-tools 1.1.8

package/src/commands/doctor.js

@@ -0,0 +1,208 @@
+import { existsSync, lstatSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { templateContent } from '../utils/template.js';
+import { loadManifest, fileState, getToolVersion, getProtectedPaths } from '../utils/manifest.js';
+import { detectStack, inferServiceName, buildContext } from '../utils/stack.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Inspect a repo against its .shiftleft.json: is the tool version behind, are
+ * any managed files out of date / locally modified / missing, are symlinks
+ * (Phase C) intact. Read-only.
+ *
+ *   --check  exit 1 if the repo is stale, drifted, or has broken symlinks
+ *   --json   emit a machine-readable report instead of the formatted one
+ */
+/**
+ * Pure inspection: returns the drift report for a repo without printing.
+ */
+export function inspect(cwd) {
+    const manifest = loadManifest(cwd);
+    const installed = getToolVersion();
+
+    if (!manifest) {
+        return { initialized: false, installed, ok: true, files: [], symlinks: [] };
+    }
+
+    const stack = manifest.stack || detectStack(cwd);
+    const context = buildContext(inferServiceName(cwd), stack);
+
+    const behind = manifest.toolVersion !== installed;
+    const files = classifyFiles(cwd, manifest, context);
+    const symlinks = classifySymlinks(cwd, manifest);
+    // A committed .claude/skills/ copy predates the plugin model (Phase C).
+    const claudeSkillsStale = existsSync(join(cwd, '.claude/skills'));
+
+    // A managed (non-scaffold) file that is out of date, drifted, or missing
+    // is a failure; scaffold files are repo-owned so their drift is expected.
+    const fileIssues = files.filter(
+        (f) => !f.scaffold && ['update-available', 'modified', 'missing'].includes(f.status)
+    );
+    const brokenLinks = symlinks.filter((s) => s.status === 'broken');
+    const ok = !behind && fileIssues.length === 0 && brokenLinks.length === 0;
+
+    return {
+        initialized: true,
+        installed,
+        repoVersion: manifest.toolVersion,
+        behind,
+        stack,
+        files,
+        symlinks,
+        protected: getProtectedPaths(manifest),
+        claudeSkillsStale,
+        fileIssues,
+        brokenLinks,
+        ok,
+    };
+}
+
+export function doctor(options = {}) {
+    const cwd = process.cwd();
+    const report = inspect(cwd);
+
+    if (!report.initialized) {
+        if (options.json) {
+            console.log(JSON.stringify({ initialized: false, installed: report.installed }, null, 2));
+        } else {
+            logger.info('This project is not managed by shiftleft-tools (no .shiftleft.json).');
+            logger.info('Run "shiftleft init-rules" or "shiftleft init-postman" to set it up.');
+        }
+        return; // not managed -> nothing to be stale; --check passes
+    }
+
+    if (options.json) {
+        const { fileIssues, brokenLinks, ...json } = report;
+        console.log(JSON.stringify(json, null, 2));
+    } else {
+        printReport(report);
+        if (report.claudeSkillsStale) {
+            logger.info('Found a committed .claude/skills/ — Claude Code skills now come from the shiftleft-tools plugin. You can delete it.');
+        }
+    }
+
+    if (options.check && !report.ok) {
+        process.exitCode = 1;
+    }
+}
+
+function classifyFiles(cwd, manifest, context) {
+    const out = [];
+    for (const [key, entry] of Object.entries(manifest.managed)) {
+        const scaffold = entry.scaffold === true;
+
+        if (!entry.template) {
+            // Pre-Phase-B entry: can only judge presence, not upstream changes.
+            out.push({ path: key, scaffold, status: existsSync(join(cwd, key)) ? 'tracked' : 'missing' });
+            continue;
+        }
+
+        let incoming;
+        try {
+            incoming = templateContent(entry.template, context, entry.template.endsWith('.ejs'));
+        } catch {
+            // Template no longer ships in this package version.
+            out.push({ path: key, scaffold, status: 'orphaned' });
+            continue;
+        }
+
+        const state = fileState(cwd, key, manifest, incoming);
+        out.push({ path: key, scaffold, status: stateToStatus(state) });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function stateToStatus(state) {
+    switch (state) {
+        case 'uptodate': return 'current';
+        case 'clean': return 'update-available';
+        case 'local-edit': return 'modified';
+        case 'missing': return 'missing';
+        default: return 'current'; // 'new' shouldn't occur for a recorded file
+    }
+}
+
+function classifySymlinks(cwd, manifest) {
+    return (manifest.symlinks || []).map((link) => {
+        const abs = join(cwd, link);
+        let stat;
+        try {
+            stat = lstatSync(abs);
+        } catch {
+            // Absent entirely — symlinks are gitignored, so this is normal on a
+            // fresh clone. Not a failure; the fix is to run `shiftleft link`.
+            return { path: link, status: 'unlinked' };
+        }
+        if (!stat.isSymbolicLink()) return { path: link, status: 'broken' };
+        // existsSync follows the link; false => dangling target.
+        return { path: link, status: existsSync(abs) ? 'ok' : 'broken' };
+    });
+}
+
+const LABEL = {
+    current: chalk.green('current'),
+    'update-available': chalk.yellow('update available'),
+    modified: chalk.yellow('modified locally'),
+    missing: chalk.red('missing'),
+    orphaned: chalk.gray('not in this version'),
+    tracked: chalk.gray('tracked'),
+};
+
+function mark(status) {
+    if (status === 'current' || status === 'ok') return chalk.green('✓');
+    if (status === 'missing' || status === 'broken') return chalk.red('✗');
+    return chalk.yellow('⚠');
+}
+
+function printReport({ installed, repoVersion, stack, behind, files, symlinks, protected: protectedPaths = [], fileIssues, brokenLinks, ok }) {
+    console.log();
+    const versionLine = behind
+        ? `${chalk.yellow('⚠ behind')} (installed ${installed}, repo ${repoVersion}) — run: shiftleft update`
+        : `${chalk.green('✓')} ${installed}`;
+    console.log(`  ${chalk.bold('Tool:')}   ${versionLine}`);
+    console.log(`  ${chalk.bold('Stack:')}  ${stack || 'unknown'}`);
+
+    console.log(`\n  ${chalk.bold('Managed files:')}`);
+    for (const f of files) {
+        const label = f.scaffold && (f.status === 'update-available' || f.status === 'modified')
+            ? chalk.gray(`${f.status === 'modified' ? 'modified' : 'differs'} (repo-owned)`)
+            : LABEL[f.status] || f.status;
+        const symbol = f.scaffold && (f.status === 'update-available' || f.status === 'modified')
+            ? chalk.green('✓')
+            : mark(f.status);
+        console.log(`    ${symbol} ${f.path}  ${label}`);
+    }
+
+    if (symlinks.length) {
+        console.log(`\n  ${chalk.bold('Symlinks:')}`);
+        for (const s of symlinks) {
+            let label;
+            if (s.status === 'ok') label = chalk.green('ok');
+            else if (s.status === 'unlinked') label = chalk.yellow('not linked (run: shiftleft link)');
+            else label = chalk.red(s.status);
+            console.log(`    ${mark(s.status)} ${s.path}  ${label}`);
+        }
+    }
+
+    if (protectedPaths.length) {
+        console.log(`\n  ${chalk.bold('Protected (repo-owned, not staged):')}`);
+        for (const p of protectedPaths) console.log(`    ${chalk.cyan('●')} postman/scripts/${p}`);
+    }
+
+    console.log();
+    if (ok) {
+        logger.success('Up to date.');
+    } else {
+        const parts = [];
+        if (behind) parts.push('tool version behind');
+        const upd = fileIssues.filter((f) => f.status === 'update-available').length;
+        const mod = fileIssues.filter((f) => f.status === 'modified').length;
+        const mis = fileIssues.filter((f) => f.status === 'missing').length;
+        if (upd) parts.push(`${upd} update(s) available`);
+        if (mod) parts.push(`${mod} modified`);
+        if (mis) parts.push(`${mis} missing`);
+        if (brokenLinks.length) parts.push(`${brokenLinks.length} broken symlink(s)`);
+        logger.warn(`${parts.join(', ')}. Run "shiftleft update".`);
+    }
+}

package/src/commands/init-postman.js

@@ -0,0 +1,298 @@
+import { existsSync } from 'fs';
+import { join, basename } from 'path';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import { copyTemplate, ensureDir } from '../utils/template.js';
+import { copyTemplateTree } from '../utils/copy-tree.js';
+import { detectStack, inferServiceName, buildContext } from '../utils/stack.js';
+import { loadManifest, createManifest, saveManifest, recordFile } from '../utils/manifest.js';
+import { stageScripts } from './run-tests.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Initialize Postman/Newman test infrastructure
+ */
+export async function initPostman(options) {
+    const cwd = process.cwd();
+    let stack = detectStack(cwd, options.stack);
+
+    if (!stack) {
+        const { chosen } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'chosen',
+                message: 'Could not detect project type. Which stack is this?',
+                choices: [
+                    { name: 'Java / Spring Boot (pom.xml)', value: 'java' },
+                    { name: 'Node.js / Express (package.json)', value: 'node' },
+                ],
+            },
+        ]);
+        stack = chosen;
+    }
+
+    let serviceName = options.name;
+    if (!serviceName) {
+        serviceName = inferServiceName(cwd);
+        if (!serviceName) {
+            const answers = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'serviceName',
+                    message: 'Enter service name:',
+                    default: basename(cwd),
+                },
+            ]);
+            serviceName = answers.serviceName;
+        }
+    }
+
+    const includeStaging = options.withStaging || false;
+    const context = buildContext(serviceName, stack, includeStaging);
+
+    const spinner = ora(`Initializing Postman test infrastructure (${stack})...`).start();
+
+    try {
+        const postmanDir = join(cwd, 'postman');
+
+        if (existsSync(postmanDir) && !options.force) {
+            spinner.warn('postman/ directory already exists. Use --force to overwrite.');
+            return;
+        }
+
+        createDirectoryStructure(cwd, stack);
+        spinner.succeed('Created directory structure');
+
+        const manifest = loadManifest(cwd) || createManifest(stack);
+        manifest.stack = stack;
+
+        const copySpinner = ora('Copying template files...').start();
+        let copied = 0;
+
+        copied += copySharedPostmanFiles(cwd, stack, context, options.force, manifest);
+        copied += copyRunAllShim(cwd, context, options.force, manifest);
+
+        if (stack === 'node') {
+            copied += copyNodeScaffold(cwd, context, options.force, manifest);
+            copyRootNodeFiles(cwd, context, options.force, manifest);
+        }
+
+        saveManifest(cwd, manifest);
+
+        copySpinner.succeed(`Copied ${copied} files`);
+
+        const stageSpinner = ora('Staging library scripts (gitignored cache)...').start();
+        const { staged } = stageScripts(cwd, { stack });
+        stageSpinner.succeed(`Staged ${staged} library scripts (refreshed automatically by shiftleft test)`);
+
+        await makeScriptsExecutable(cwd);
+
+        printNextSteps(stack, includeStaging);
+    } catch (error) {
+        spinner.fail('Failed to initialize Postman infrastructure');
+        logger.error(error.message);
+        process.exit(1);
+    }
+}
+
+function createDirectoryStructure(cwd, stack) {
+    const dirs = [
+        'postman',
+        'postman/.husky',
+        'postman/collections',
+        'postman/config',
+        'postman/environments',
+        'postman/reports',
+        'postman/scripts',
+        'postman/scripts/lib',
+        'postman/scripts/runners',
+        'postman/scripts/report-generators',
+        'postman/scripts/auth',
+    ];
+
+    if (stack === 'java') {
+        dirs.push('postman/scripts/infra', 'postman/scripts/wiremock', 'postman/scripts/wiremock/mappings');
+    } else {
+        dirs.push(
+            'postman/scripts/database',
+            'postman/mocks',
+            'postman/collections/crud',
+            'postman/seeders/global',
+            'postman/test_data',
+        );
+    }
+
+    for (const dir of dirs) {
+        ensureDir(join(cwd, dir));
+    }
+}
+
+function copySharedPostmanFiles(cwd, stack, context, force, manifest) {
+    let copied = 0;
+    const files = [
+        // Shipped under non-dot names: npm pack always strips .npmrc/.gitignore,
+        // and a nested .gitignore would also exclude the staged-script templates.
+        { src: 'postman/npmrc', dest: 'postman/.npmrc' },
+        { src: 'postman/gitignore', dest: 'postman/.gitignore' },
+        { src: 'postman/.prettierrc.json', dest: 'postman/.prettierrc.json' },
+        { src: 'postman/.husky/pre-commit', dest: 'postman/.husky/pre-commit' },
+        {
+            src: stack === 'node' ? 'postman-node/package.json.ejs' : 'postman/package.json.ejs',
+            dest: 'postman/package.json',
+            render: true,
+        },
+        {
+            src: stack === 'node' ? 'postman-node/README.md.ejs' : 'postman/README.md.ejs',
+            dest: 'postman/README.md',
+            render: true,
+        },
+        {
+            src: 'postman/environments/local.postman_environment.json.ejs',
+            dest: 'postman/environments/local.postman_environment.json',
+            render: true,
+        },
+        {
+            src: stack === 'node' ? 'postman-node/config/local.json.ejs' : 'postman/config/local.json.ejs',
+            dest: 'postman/config/local.json',
+            render: true,
+        },
+    ];
+
+    if (context.includeStaging) {
+        files.push(
+            {
+                src: 'postman/environments/staging.postman_environment.json.ejs',
+                dest: 'postman/environments/staging.postman_environment.json',
+                render: true,
+            },
+            {
+                src: stack === 'node' ? 'postman-node/config/staging.json.ejs' : 'postman/config/staging.json.ejs',
+                dest: 'postman/config/staging.json',
+                render: true,
+            },
+        );
+    }
+
+    if (stack === 'java') {
+        files.push({
+            src: 'postman/collections/01-core.json.ejs',
+            dest: 'postman/collections/01-core.json',
+            render: true,
+        });
+    } else {
+        files.push({
+            src: 'postman-node/collections/crud/01-bootstrap.json.ejs',
+            dest: 'postman/collections/crud/01-bootstrap.json',
+            render: true,
+        });
+    }
+
+    for (const file of files) {
+        const destPath = join(cwd, file.dest);
+        try {
+            const result = copyTemplate(file.src, destPath, context, { render: file.render || false, force });
+            if (!result.skipped) {
+                recordFile(manifest, cwd, destPath, result.content, { scaffold: true, template: file.src });
+            }
+            copied++;
+        } catch (err) {
+            logger.warn(`Could not copy ${file.src}: ${err.message}`);
+        }
+    }
+
+    return copied;
+}
+
+function copyRunAllShim(cwd, context, force, manifest) {
+    const dest = join(cwd, 'postman/scripts/run-all.sh');
+    const result = copyTemplate('postman/run-all-shim.sh', dest, context, { force });
+    if (!result.skipped) {
+        recordFile(manifest, cwd, dest, result.content, { template: 'postman/run-all-shim.sh' });
+    }
+    return result.skipped ? 0 : 1;
+}
+
+function copyNodeScaffold(cwd, context, force, manifest) {
+    let copied = 0;
+
+    // App-runtime mock orchestrator, customized per service — repo-owned.
+    const mocksEntry = copyTemplate('postman-node/scripts/setup-mocks.js.ejs',
+        join(cwd, 'postman/scripts/setup-mocks.js'), context, { render: true, force });
+    if (!mocksEntry.skipped) {
+        recordFile(manifest, cwd, join(cwd, 'postman/scripts/setup-mocks.js'), mocksEntry.content, {
+            scaffold: true,
+            template: 'postman-node/scripts/setup-mocks.js.ejs',
+        });
+        copied++;
+    }
+
+    // Mocks are a starter the repo customizes — record as scaffold (repo-owned).
+    copied += copyTemplateTree('postman-node/mocks', join(cwd, 'postman/mocks'), context, {
+        force,
+        manifest,
+        cwd,
+        scaffold: true,
+    }).copied;
+
+    return copied;
+}
+
+function copyRootNodeFiles(cwd, context, force, manifest) {
+    const reqs = copyTemplate('postman-node/requirements.txt', join(cwd, 'requirements.txt'), context, { force });
+    if (!reqs.skipped) recordFile(manifest, cwd, join(cwd, 'requirements.txt'), reqs.content, { scaffold: true, template: 'postman-node/requirements.txt' });
+
+    const env = copyTemplate('postman-node/local.test.env.ejs', join(cwd, 'postman/local.test.env'), context, {
+        render: true,
+        force,
+    });
+    if (!env.skipped) recordFile(manifest, cwd, join(cwd, 'postman/local.test.env'), env.content, { scaffold: true, template: 'postman-node/local.test.env.ejs' });
+
+    const strykerDest = join(cwd, 'stryker.config.js');
+    if (!existsSync(strykerDest) || force) {
+        const stryker = copyTemplate('postman-node/stryker.config.js.ejs', strykerDest, context, { render: true, force });
+        if (!stryker.skipped) recordFile(manifest, cwd, strykerDest, stryker.content, { scaffold: true, template: 'postman-node/stryker.config.js.ejs' });
+        logger.success('Created stryker.config.js (customize mutate paths for your src/)');
+    } else {
+        logger.skip('Skipped stryker.config.js (already exists)');
+    }
+}
+
+async function makeScriptsExecutable(cwd) {
+    const makeExecutable = ora('Making scripts executable...').start();
+    const { execSync } = await import('child_process');
+    try {
+        execSync(`find ${join(cwd, 'postman/scripts')} -name "*.sh" -exec chmod +x {} \\;`, { stdio: 'ignore' });
+        execSync(`chmod +x ${join(cwd, 'postman/.husky/pre-commit')}`, { stdio: 'ignore' });
+        makeExecutable.succeed('Scripts are executable');
+    } catch {
+        makeExecutable.warn('Could not make scripts executable (run chmod +x manually)');
+    }
+}
+
+function printNextSteps(stack, includeStaging) {
+    console.log();
+    logger.success('Postman test infrastructure initialized!');
+    console.log();
+    logger.info('Next steps:');
+    console.log('  1. cd postman && npm install');
+    console.log('  2. Update postman/config/local.json with your API URL, port, and auth settings');
+    if (stack === 'node') {
+        console.log('  3. Wire setup-mocks.js into your app entry when NODE_ENV=integration-tests');
+        console.log('  4. Customize stryker.config.js mutate paths for your src/ layout');
+        console.log('  5. Add collections under postman/collections/crud/');
+        console.log('  6. Run: shiftleft test   (or: postman/scripts/run-all.sh)');
+    } else {
+        console.log('  3. Add your first test collection in postman/collections/');
+        console.log('  4. Run: shiftleft test   (or: postman/scripts/run-all.sh)');
+    }
+    console.log();
+    logger.info('Library scripts are staged from the shiftleft-tools package (gitignored) and refresh on every run.');
+    if (!includeStaging) {
+        console.log();
+        logger.info('Tip: Run "shiftleft init-postman --with-staging" to add staging support later.');
+    }
+    if (stack === 'node') {
+        console.log();
+        logger.info('Invoke /setup-api-tests in Cursor or Claude Code for guided Node Postman setup.');
+    }
+}

package/src/commands/init-rules.js

@@ -0,0 +1,78 @@
+import { join } from 'path';
+import { copyTemplate } from '../utils/template.js';
+import { detectStack } from '../utils/stack.js';
+import { loadManifest, createManifest, saveManifest, recordFile } from '../utils/manifest.js';
+import { linkAssets } from './link.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Initialize Cursor rules/skills and the agent guide files in the project.
+ *
+ * Cursor skills and rules are linked to the installed shiftleft-tools package
+ * (symlinks, gitignored) so they update with a single global install. Claude
+ * Code skills are provided by the shiftleft-tools plugin, not copied per repo.
+ * CLAUDE.md / AGENTS.md remain real, manifest-managed files.
+ */
+export async function initRules(options) {
+    const cwd = process.cwd();
+    const stack = detectStack(cwd, options.stack);
+    const manifest = loadManifest(cwd) || createManifest(stack);
+    manifest.stack = manifest.stack || stack;
+
+    try {
+        const { linked, copied, symlinkMode } = linkAssets(cwd, {
+            stack,
+            skills: !options.skipSkills,
+            rules: true,
+            copy: options.copy,
+            manifest,
+        });
+
+        if (symlinkMode) {
+            logger.success(`Linked ${linked.length} Cursor asset(s) to the shiftleft-tools package (symlinks, gitignored)`);
+        } else {
+            logger.success(`Copied ${copied.length} Cursor asset(s) (symlinks unavailable)`);
+        }
+
+        copyClaude(cwd, options, manifest);
+        copyAgents(cwd, options, manifest);
+
+        saveManifest(cwd, manifest);
+
+        console.log();
+        logger.info('Cursor rules and skills initialized.');
+        logger.info('Claude Code skills come from the shiftleft-tools plugin — install it once (see README), not per repo.');
+        logger.info('Run "shiftleft update --rules" to refresh links later.');
+    } catch (error) {
+        logger.error(`Failed to initialize rules: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+/** Record a copyTemplate result in the manifest when it actually wrote a file. */
+function record(manifest, cwd, templatePath, result) {
+    if (result && !result.skipped) {
+        recordFile(manifest, cwd, result.path, result.content, { template: templatePath });
+    }
+    return result;
+}
+
+function copyClaude(cwd, options, manifest) {
+    const claudeMdDest = join(cwd, 'CLAUDE.md');
+    const result = record(manifest, cwd, 'CLAUDE.md', copyTemplate('CLAUDE.md', claudeMdDest, {}, { force: options.force }));
+    if (result.skipped) {
+        logger.skip('Skipped CLAUDE.md (already exists, use --force to overwrite)');
+    } else {
+        logger.success('Created CLAUDE.md');
+    }
+}
+
+function copyAgents(cwd, options, manifest) {
+    const agentsMdDest = join(cwd, 'AGENTS.md');
+    const result = record(manifest, cwd, 'AGENTS.md', copyTemplate('AGENTS.md', agentsMdDest, {}, { force: options.force }));
+    if (result.skipped) {
+        logger.skip('Skipped AGENTS.md (already exists, use --force to overwrite)');
+    } else {
+        logger.success('Created AGENTS.md');
+    }
+}